Skip to content

v4.0.0 — The Agent-Era Update

Choose a tag to compare

View all tags
@munair munair released this 13 Apr 09:28
· 18 commits to main since this release
v4.0.0
1094187

v4.0.0 — The Agent-Era Update

All existing guidelines have been updated to assume a tool-using coding agent — not a chat-loop assistant. Two new guidelines and one new repository convention were added. Existing v3.x PRDs remain readable and valid; this release is tagged 4.0.0 because new v4.0.0-conformant PRDs expect a WORKFLOW.md policy file at the repository root, every PRD structure now includes an Agent Execution Plan section, the guideline taxonomy grew from four to six, and the recommended activation prompts changed.

Why a Major Version

Over the 12 months since v3.0.0, coding agents gained capabilities the framework did not model:

  • Tool use — agents read files, run tests, grep the codebase, commit their own work
  • Subagents — broad research and parallel work can be delegated
  • Hooks — deterministic rules are enforced by scripts, not by prose instruction
  • Workspace isolation — per-feature branches or git worktrees
  • Skills / slash commands — reusable capability bundles
  • Long-running background agents — orchestrators that consume issues from trackers

v3.x guidelines treated the "AI assistant" as a single chat loop. v4.0.0 treats it as an agent with tools, subagents, and policy-enforcing hooks. The philosophy — "build the fence, explore the playground" — is unchanged. What changed is who's holding the shovel.

New Guidelines

guidelines/system-specification-guidelines.md

The fifth PRD guideline, for specifying multi-component systems: orchestrators, daemons, long-running services, and anything with a non-trivial state machine, streaming transport, or audit obligation. Fills the gap between feature-level PRDs (Backend/Frontend) and system-level specifications.

Section spine (adapted from OpenAI's Symphony SPEC.md, extended with cross-cutting concerns that used to be homeless):

§ Section What it covers
1 Problem & Goals Operational problems solved; measurable success; explicit out-of-scope
2 System Architecture Component table with responsibility, inputs, outputs, lifecycle
3 Domain Model Stable entity IDs, field lists, identity discipline, lifecycles
4 Service Policy / Configuration File The service's own in-repo config file — with a naming note distinguishing it from the project WORKFLOW.md
5 State Machine & Orchestration States, transitions, invariants, concurrency rules, retry, reconciliation
6 Streaming Transports (new) SSE/WS/long-poll/gRPC/broker fan-out — transport choice, schema, backpressure, reconnect/resume, heartbeat, multi-subscriber semantics, graceful drain, testing hooks, frontend handoff
7 Audit & Compliance Records (new) Scope, schema, retention/immutability (WORM, hash chaining, GDPR), PII/secret handling, access control, export/replay, fail-closed vs fail-open write path, optional regulatory mapping
8 Safety & Integration Trust boundaries, workspace isolation, external integrations, failure domains
9 Observability & Operations Structured logging, metrics, status surfaces, operator intervention, alerts
10 Testing Matrix Per-component rows with verification commands
11 Agent Execution Plan Branch, subagent delegation, hook requirements, WORKFLOW.md reference
12 Extensibility How to add components, config fields, states, streaming message types, audit event types
13 Non-Goals Explicit exclusions
14 Open Questions Unresolved items with owner and resolution date

Use it when: you're specifying an orchestrator, daemon, long-running service, a service that owns a streaming transport, or any feature with audit/compliance obligations.

Don't use it when: you're specifying a single Lambda or a single React component — the Backend or Frontend guideline is the right fit.

guidelines/workflow-file-guidelines.md

Defines the WORKFLOW.md in-repository policy file convention. WORKFLOW.md (or CLAUDE.md, AGENTS.md, .cursorrules, depending on harness) is the single source of truth for project-wide rules:

  • Test commands and pass criteria
  • Branch policy (feature branches, worktrees, main protection)
  • Commit message format
  • Hook configuration
  • Subagent delegation defaults
  • Archival protocol reference
  • Project-specific conventions

The rule: If a rule applies to every feature in this project, it belongs in WORKFLOW.md — not restated in every PRD. PRDs reference the file; hooks enforce it; agents read it.

templates/workflow-template.md

A reference WORKFLOW.md with:

  • Optional YAML front matter (forward-compatible: unknown keys ignored)
  • Test command section framed as "delete what doesn't apply"
  • Branch policy section
  • Commit style section
  • Valid Claude Code hook JSONC — matcher regex against tool name, hooks[].type/command structure, and a reference pre-commit-gate.sh script that parses stdin and only runs tests/lint/typecheck when the Bash command contains git commit
  • Subagent delegation defaults
  • Archival protocol reference
  • Project-specific placeholder section
  • Forward compatibility rule
  • Explicit "What does NOT belong here" section

Changes to Existing Guidelines

Every guideline gained an Agent-Era Execution Model section

Backend, Frontend, Exploratory, and Tasks guidelines each gained a new §0 Agent-Era Execution Model section plus targeted updates throughout. The changes are surgical — the "build the fence, explore the playground" philosophy is intact — but every guideline now expects:

  1. The agent has tools (reads files, runs tests, commits)
  2. The agent can spawn subagents (Explore for recon, Plan for second opinions)
  3. The agent honors in-repository policy (reads WORKFLOW.md)
  4. Hooks replace prose instruction for deterministic rules
  5. Work happens in an isolated workspace (branch or worktree)
  6. Requirements are machine-verifiable (test assertions, not prose judgments)

PRDs written under v4.0.0 are shorter because they reference project conventions instead of restating them.

Backend & Frontend guidelines: Agent Delegation Strategy

Both guidelines gained a section with a table of typical delegation candidates and a standard "Delegatable Research" format for PRDs to hoist recon work to subagents before writing implementation tasks.

Frontend guideline: Spanning Requirements are always split

The [Both] spanning-requirement escape hatch is removed. When a single feature requirement touches both layers, always split it into separate FRs — one per layer. A "How to identify a spanning requirement" paragraph replaces the escape hatch with a concrete three-question test.

Frontend guideline: one Consolidated Final Audit

The Boundary Checklist (v2.x), Architectural Audit (v3.0.0), and Agent Orchestration Audit (early v4) are consolidated into a single Final Audit at §5. One checklist, no duplicates. Red-flag items include prose rules the agent must "remember" (should be hooks), acceptance criteria that aren't machine-verifiable, restated WORKFLOW.md contents inline, sequential task lists that could be parallelized with subagents, streaming transport specified in a frontend PRD rather than routed to System, and 3+ (not 2+) sequential API calls to hydrate a non-gated view — user-gated drill-downs, lazy tabs, and code-split routes are explicitly carved out.

Frontend guideline: streaming and audit route to System

The decision framework's streaming and audit rows now route to system-specification-guidelines.md §6/§7 instead of reproducing partial guidance. The frontend PRD owns its side of the contract (render, stale-frame detection, reconnect UX, error surfacing); the system spec owns the transport, schema, backpressure, and retention.

Exploratory guideline: Recon Findings moved upstream

Recon Findings moved from §6.5 (after creative sections) to §0.5 (before §1 The Spark), matching the §0 instruction that says recon runs first and is summarized before creative work begins.

Tasks guideline: Agent Execution Model + new task format

A new first-class section explains how tasks are now executed by tool-using agents, including:

  • Tasks executed directly (not suggestions for a human)
  • Isolated workspace requirement
  • Hook-enforced deterministic rules
  • [parallel] marker for parallelizable tasks
  • Delegatable research hoisted to subagents
  • Every task has a verification step
  • WORKFLOW.md contract

The task format example gains: branch name at the top, reference to WORKFLOW.md (not restated), required hooks listed explicitly, Phase 0: Recon for subagent-delegated research, [parallel] markers on independent phases, explicit verification commands on every sub-task, and a Delegated Work summary section.

Repository Infrastructure

.claude/hooks/protect-env.sh

The .env-protection hook had multiple bypass vectors closed before shipping. Verified against a 33-case deny/allow test suite.

  • Fail-closed on parse errors. jq failures, missing input, and unexpected tool shapes now deny rather than pass through.
  • Shell-quote stripping before matching. bash -c 'printenv' and sh -c "cat .env" are caught. Previously the word-boundary regex failed inside quoted subcommand content.
  • .env.example allowlist scoped to path fields only. Decoy strings like cat .env # see .env.example cannot bypass the block.
  • Redirect and subshell boundaries. head <.env, $(cat .env), and backtick subshells are caught.
  • Env-dump coverage extended. export -p, declare -x, /proc/*/environ, ps -E (macOS), and ps eww/ps eaww (BSD-style) are blocked alongside env/printenv.
  • Bulk archive from repo root. tar/rsync/cpio sourced from ././/$PWD, and cp -r . / zip -r . are blocked — these tools copy the repo wholesale including the real .env without ever naming it.
  • Case-insensitive matching. .ENV blocks on macOS (HFS+ is case-insensitive by default).
  • Denial logging to ~/.claude/protect-env.log with timestamp, tool name, and reason.

.claude/settings.json

  • Matcher extended to cover Task|WebFetch|WebSearch|NotebookEdit in addition to Read|Write|Edit|Bash|Grep|Glob.
  • .env* deny rules duplicated from Read to Edit/Write/Grep/Glob as defense-in-depth.

Canonical documentation directories

.gitkeep scaffolding ships for /documentation/specifications/active/, /documentation/specifications/completed/, /documentation/tasks/active/, and /documentation/tasks/completed/. Previously the convention was documented but the directories had to be created by hand on a fresh clone.

Migration: v3.x → v4.0.0

PRD format is not broken. Existing v3.x PRDs remain valid. To fully adopt v4.0.0:

  1. Copy templates/workflow-template.md to your project root as WORKFLOW.md. Fill in test commands, branch policy, and project-specific rules.
  2. Wire up hooks from the template into .claude/settings.json (or your harness equivalent). Start with PreToolUse(Bash:git commit) running tests, and Stop running archival verification.
  3. Audit existing PRDs: wherever they restate a rule that now lives in WORKFLOW.md, delete the duplication and add a reference.
  4. Update activation prompts to mention WORKFLOW.md and subagent delegation. See README.md for the new prompt templates.
  5. For your next multi-component project, use system-specification-guidelines.md instead of cramming it into a Backend PRD.

Worked Example

v3.x PRD (excerpt) — rules restated inline:

## Testing
The following must pass before any commit:
- `node --test tests/` for backend tests
- `npm run lint` for linting
- `npm run typecheck` for TypeScript

## Branch Policy
Work on a feature branch named `feature/[slug]`. Do not commit to `main`.

## Commit Format
Use Conventional Commits: `feat(scope): message`.

## Functional Requirements
- FR1: Backend: Add a new endpoint `/accounts/{id}/summary` that returns...
- FR2: Backend: The endpoint must be authenticated via existing middleware...

v4.0.0 PRD (excerpt) — rules hoisted into WORKFLOW.md, referenced:

## Agent Execution Plan
- **Branch**: `feature/account-summary-endpoint` (see WORKFLOW.md branch policy)
- **Tests, lint, typecheck, commit format**: inherited from WORKFLOW.md
- **Required hooks**: PreToolUse(Bash:git commit) runs tests (enforced by
  .claude/settings.json)
- **Delegatable research**:
  - [Explore subagent] Map existing /accounts/* handlers and their auth
    middleware usage.
  - [Explore subagent] Identify DynamoDB access patterns already used for
    the accounts table.

## Functional Requirements
- FR1: Backend: Add a new endpoint `/accounts/{id}/summary` that returns...
- FR2: Backend: The endpoint must be authenticated via existing middleware...

The testing, branch-policy, and commit-format sections are gone — they live in WORKFLOW.md and are enforced by hooks. Only the work that is specific to this feature remains in the PRD.

Unchanged from v3.0.0

  • The "build the fence, explore the playground" philosophy
  • The [Backend/Frontend] prefix requirement in functional requirements
  • The Architectural Boundaries Framework
  • The 5-Question Decision Framework
  • The ARCHIVAL PROTOCOL (now additionally hook-enforceable)
  • The Quick Start vs. Full PRD distinction
  • The /documentation/specifications/{active,completed}/ and /documentation/tasks/{active,completed}/ directory conventions (now shipped with .gitkeep scaffolding)

Full CHANGELOG

See CHANGELOG.md for the complete release notes, including the full Added / Changed / Fixed breakdown and additional context.

Inspiration

The new System guideline's section spine was adapted from OpenAI's Symphony SPEC.md — a reference specification for a long-running agent-orchestration service. Symphony itself is not a guideline; it is an example of what a rigorous system-level spec looks like. This framework extracted its structure into a reusable template and extended it with the Streaming Transports and Audit & Compliance Records sections.

Assets 2
Loading