v4.0.2 polish pass: validation vocabulary, audit parity, pseudocode discipline

Summary

A second polish pass against v4.0.1, additive only. No new required PRD sections, no changes to existing PRD structure, no breaking changes to any guideline contract. v4.0.1 PRDs remain valid and conformant. Three themes: a named failure taxonomy for specification reviews, parity in the Final Audit surface across all four PRD guidelines, and reference pseudocode blocks for the two parts of the framework where ordering and error paths are most load-bearing. Shipped as a 4.0.2 patch release.

What's new

• guidelines/specification-validation-vocabulary.md (new file). ~50 named failure codes a specification reviewer (human or subagent) can cite when auditing a PRD, system spec, task list, or WORKFLOW.md. Each entry has a stable snake_case identifier, a one-line description, the guideline section it belongs to, and example failure/fix pairs. Adapted from the OpenAI Symphony SPEC.md §5.5 error-taxonomy pattern, where every validation failure has a stable name so hooks, tooling, and reviewers can reference the same concept without re-inventing vocabulary every time. Organized into Cross-Guideline, Backend, Frontend, System, Implementation Tasks, Workflow File, and Exploratory categories. Includes Conformance Profiles (Core / Extension / Integration) for tiering audits by spec type, and a forward-compatibility rule (unknown codes in audit output are ignored with a warning, never rejected).

• Final Audit parity across all four PRD guidelines. v4.0.1 added a Final Audit to the Backend guideline (Gap 9) but left the System and Exploratory guidelines without one. v4.0.2 closes that asymmetry:

  • System guideline gains a full Final Audit with Structural Completeness, Cross-Cutting Concerns (streaming and audit), Testing & Execution, and Red Flags subsections. Every checkbox and red-flag bullet cites a stable identifier from the new vocabulary.
  • Exploratory guideline gains a deliberately lightweight §6.5 Final Audit. Five checks for the failure modes that would cause downstream rework — skipped recon, contradicted constraints, ambiguous migration target. Short on purpose, because exploratory documents are scratch space for creative work, not contracts the agent will execute.

• Backpatched vocabulary citations on existing audits. Every red-flag bullet and every checkbox in the Backend §PRD Review Checkpoint and the Frontend §5 Final Audit now carries a parenthetical vocabulary code. Wording is unchanged; the codes are additive metadata that lets reviewer subagents and hooks cite findings by stable name rather than re-describing them in prose, and lets external tools grep audit output for code names.

• "When to Use This Guideline (and When Not To)" blocks on Backend and Frontend. Matches the existing block in the System guideline. An agent picking the wrong guideline catches the mistake before writing the PRD instead of after. Each block lists "use this for" with concrete cases and "do not use this for" with explicit redirects to the right guideline (streaming → System §6, audit → System §7, multi-component service → System, etc.).

• Reference pseudocode blocks in two guidelines. The framework now treats pseudocode as a first-class tool for specification authors, not a stylistic flourish:

  • guidelines/system-specification-guidelines.md — IssueState state machine. A worked pseudocode block in the Symphony-like example section. Demonstrates how pseudocode resolves the audit-write ordering question that prose §7.7 hedges around: audit write happens before the state transition, workspace release is gated on the transition completing, reconciliation distinguishes "in-flight with recent heartbeat" from "in-flight but stale." Closes ambiguity that prose alone could not.
  • guidelines/implementation-tasks-creation-guidelines.md — agent PRD-execution loop. Pins down the gates that hooks enforce: audit before branch creation, recon before plan, user confirmation as a hard gate, per-task verification, archival gated by the Stop hook. The agent's PRD-consumption loop is now a contract, not a prose narrative.

• README.md — "The Case for Pseudocode in Specifications." A new educational section between the Sample Interaction Flow and "What the Framework Aims to Produce." Covers what pseudocode is in this framework (language-neutral, ordered, named-step descriptions of control flow); why it beats prose for hard parts of a spec (with a worked before/after audit-write example); pseudocode as a forcing function for the author rather than a translation hint for the implementer; pseudocode as a contract that commits to ordering/invariants/error-paths while staying silent about syntax/libraries/types; when to write it (state machines, ordering-dependent algorithms, reconciliation logic, multi-step transactions, agent-execution loops); when not to (simple CRUD, UI rendering, configuration shapes, anything over ~30 lines); and a reading order for the two pseudocode blocks shipped here.

• guidelines/README.md indexes the new validation vocabulary file under a "Validation Vocabulary (1) — NEW in v4.0.2" subsection so adopters reading the directory index can find it.

Commits

One commit per concern, in safest-first order:

1. 55eac8c — docs(guidelines): add specification validation vocabulary
2. e985f2f — docs(guidelines): cite vocabulary codes in backend/frontend Final Audits
3. 5d13f75 — docs(system): add Final Audit and reference IssueState pseudocode
4. ec0b86b — docs(exploratory): add lightweight Final Audit (§6.5)
5. 644611f — docs(tasks): add reference pseudocode for the agent PRD-execution loop
6. e4775b9 — docs(readme): add 'The Case for Pseudocode in Specifications' section
7. 80bcd89 — docs(changelog): 4.0.2 validation vocabulary and pseudocode entry

Merged via PR #3 as merge commit 90eaee6.

Why this is a patch release

Per WORKFLOW.md §7 version-bump rules, a patch release is "corrections, clarifications, and editorial polish that do not change expectations." v4.0.2 meets that bar:

• No new required PRD sections. Every section added is either internal (Final Audit, which lives in the guideline file rather than the resulting PRD) or additive (the vocabulary file is a new artifact that existing PRDs do not need to reference).
• No structural changes to existing PRDs. v4.0.1 PRDs remain valid and conformant. The only thing that has changed is that a reviewer auditing them now has stable identifiers for findings.
• No new required artifacts at the project root. v4.0.0 already requires WORKFLOW.md; v4.0.2 does not require anything new.
• All edits are additive. Backpatching parenthetical codes onto existing checkboxes does not alter their semantics; new sections live alongside the existing structure rather than replacing it.

Version note

package.json is deliberately not bumped, mirroring v4.0.1. The polish pass ships as a 4.0.2 changelog entry. The v4.0.2 git tag was pushed to origin alongside this release.

Scope discipline

• No new guidelines added in the PRD-generating sense — specification-validation-vocabulary.md is a reference artifact for reviewers, not a guideline that produces a PRD.
• No existing guidelines rewritten wholesale — every audit edit is additive metadata or a new section appended.
• No structural change to any existing PRD spine.
• .claude/settings.json, the env-protection hook, and infrastructure outside the guideline content are untouched.
• main was never committed to directly and was never force-pushed.

🤖 Generated with Claude Code

v4.0.1 Polish Pass: examples, templates, hook scripts, backend audit parity, dogfood WORKFLOW.md

Summary

A nine-gap polish pass against v4.0.0 (shipped on main at 1094187). No new guidelines, no new philosophy, no structural changes to the framework contract — every change closes a concrete gap between what v4.0.0's release notes promised and what actually shipped. Intended as a 4.0.1 patch release.

Gaps closed

• Gap 1 — v4.0.0 worked example PRDs. examples/ previously held only two v1.x specifications that predated the Agent-Era Update. Adds three plausible-but-fictional worked examples illustrating the v4.0.0 shape end to end: a backend Lambda PRD, a frontend React component PRD with a correctly split spanning requirement, and a system-level specification populating all 14 sections including Streaming Transports and Audit & Compliance Records (with an explicit fail-closed audit decision). examples/README.md is updated to distinguish v4.0.0 reference examples from v1.x legacy examples.
• Gap 2 — system-specification template. templates/ had no template for the new System guideline. Adds templates/system-specification-template.md mirroring the 14-section spine with one-line placeholder prompts per section; optional cross-cutting sections (§6, §7) are marked "delete if not applicable."
• Gap 3 — reference hook scripts. templates/workflow-template.md §4 named three scripts (pre-commit-gate, verify-archival, session-bootstrap) but shipped only a minimal inline body for one of them. Ships all three as copy-ready .bash files under templates/scripts/, invoked via bash <path>.bash. pre-commit-gate.bash is fail-closed on jq/stdin parse errors and emits the Claude Code deny JSON shape; verify-archival.bash reports every offending implementation log; session-bootstrap.bash is a read-only one-line situational summary. Template §4 is updated to point at the shipped files.
• Gap 4 — implementation-tasks-creation-guidelines.md Process section aligned with the Agent Execution Model section at the top of the same file. Five corrections: Step 0 now names WORKFLOW.md as the authoritative source; Step 1's dangling reference to the non-existent guidelines-for-clarifying-feature-specifications.md is replaced with a pointer to the actual PRD generation guidelines; Steps 2–3 name tools explicitly (Read/Grep/Glob, Explore subagent for surveys > ~5 files); a new Step 3.5 makes it explicit that the agent spawns the PRD's Delegatable Research subagents in parallel before proposing the plan; and Step 4's prompt now tells the user to respond with "Let's boogie!" to match Step 5's wait condition (the fun phrase is deliberately preserved).
• Gap 5 — stale cross-reference in workflow-file-guidelines.md. The "How This Integrates with the Other Guidelines" section previously claimed that the System guideline's "Workflow / Policy File" section is the system's own version of the WORKFLOW.md convention. That framing was wrong: the section was renamed in v4.0.0 to "Service Policy / Configuration File" specifically to disambiguate it from the project-level WORKFLOW.md, and a service's operational configuration is a different artifact. Bullet rewritten to make the distinction explicit.
• Gap 6 — search-and-replace residue (configuration␣␣). Recorded but no-op: already fixed during v4.0.0 development in commit 1094187. Grep confirmed zero hits across the repository. The v4.0.1 changelog entry records the audit result for completeness.
• Gap 7 — blank-line formatting. Several files had blank lines removed between headings by an earlier formatter pass, leaving headings that abutted their predecessors. Inserts exactly one blank line before every ## and ### heading that needed one across seven files. Wording unchanged. Intentional Markdown hard-break trailing spaces in the exploratory guideline are preserved. Headings inside fenced code blocks (example PRD structures) are deliberately left alone.
• Gap 8 — /WORKFLOW.md at the repository root (dog food). This framework told every adopting project to place a WORKFLOW.md at its root, but the framework itself did not have one. Adds /WORKFLOW.md encoding this repository's actual rules: §1 Test Commands explicitly states the repository is documentation-only and no PreToolUse(Bash:git commit) hook is wired (with rationale so the absence isn't mistaken for an oversight); §2 Branch Policy; §3 Commit Style; §4 Hook Configuration pointing at existing .claude/settings.json and protect-env.sh; §5–6 subagent defaults and archival protocol; §7 Project-Specific Conventions covering changelog discipline, version-bump rules, directory layout, the dog-food rule, the no-abbreviations rule, and the .bash script convention. README.md and guidelines/workflow-file-guidelines.md now reference /WORKFLOW.md as a live worked example alongside the abstract template.
• Gap 9 — backend guideline parity with frontend. The backend guideline previously lacked both a named "Before Asking Anything — Use Tools First" subsection and a "PRD Review Checkpoint: Final Audit" section that frontend has at §5. Structural asymmetry sent an unintended signal that backend PRDs received less review rigor than frontend PRDs, which is the opposite of what the framework wants for the layer that holds business logic, security, and data integrity. Full parity, not trimmed: the audit is a review step the agent runs on a finished PRD — its length lives in the guideline file, not the resulting PRDs, so "keep it short to avoid bloating PRDs" was a category error. Backend has its own red-flag surface area comparable to frontend's (non-idempotent write endpoints, missing error envelopes, IAM overreach, fail-open audit on audit-relevant paths, multi-table writes without a transactional story, response shapes driven by a single current caller, and so on). Backend guideline grows from 154 to 206 lines; still materially shorter than frontend's 542 because frontend has content backend does not need.

Commits

One commit per gap in Conventional Commits style, in a sensible safest-first order:

1. 7221f08 — style(docs): normalize blank lines before headings (Gap 7)
2. 7fa12ee — docs(workflow): fix stale System Spec cross-reference (Gap 5)
3. 94e2deb — docs(tasks): align Process section with Agent Execution Model (Gap 4)
4. 5d93a74 — docs(templates): ship reference hook scripts (Gap 3)
5. 3ed5786 — docs(templates): add system-specification template (Gap 2)
6. 357d1e9 — docs(examples): add v4.0.0 worked example PRDs (Gap 1)
7. b3bd7c1 — docs: add WORKFLOW.md at repository root; dogfood v4.0.0 (Gap 8)
8. 0573c92 — docs(backend): add Final Audit and tools-first subsection (Gap 9)
9. 3621426 — docs(changelog): 4.0.1 polish pass entry

Version note

package.json is deliberately not bumped. v4.0.0 was already released on GitHub at that version string; the polish pass ships as a 4.0.1 changelog entry without rolling the package.json version forward. A v4.0.1 git tag was pushed to origin alongside this release.

Scope discipline

• No new guidelines added.
• No existing guidelines rewritten wholesale.
• No new philosophical concepts, taxonomy entries, or section types in the spines.
• .claude/settings.json, the f55fad9 env-protection changes, and infrastructure outside the guideline content are untouched.
• main was never committed to directly and was never force-pushed.

🤖 Generated with Claude Code

v4.0.0 — The Agent-Era Update

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 failu...

v3.0.0 - Architectural Decision Framework

🎯 Major Architectural Framework Addition

BREAKING CHANGES: Complete architectural decision framework for frontend/backend responsibility separation.

This release represents a fundamental paradigm shift in how AI assistants generate PRDs, preventing common mistakes where business logic defaults to the frontend.

---

🚀 Key Features

Section 2: Architectural Boundaries Framework (113 lines)

Backend Responsibilities:

• Business logic, data aggregations, heavy computations
• Multi-symbol operations, data normalization
• Security operations, caching, external API integration

Frontend Responsibilities:

• UI state management, presentation logic
• Progressive disclosure, client-side validation
• Visual calculations, user preferences

5-Question Decision Framework:

1. Does this require data from multiple sources?
2. Is this a calculation or transformation?
3. Will multiple clients need this?
4. Does this affect performance?
5. Is this security-sensitive or rate-limited?

Enhanced PRD Requirements

• Mandatory [Backend/Frontend] prefix in functional requirements
• Required "Architectural Decisions" section in both Quick Start and Full PRD
• Format: FR1: Backend: Calculate P/C ratios during options chain processing

PRD Review Checkpoint: Architectural Audit

• 5-point checklist before finalizing PRD
• Red flags detection system
• Self-auditing capability for AI assistants

---

💡 The Problem This Solves

Before v3.0.0, AI-generated PRDs frequently contained these anti-patterns:

• ❌ "Frontend calculates P/C ratio from options data"
• ❌ "Frontend fetches multiple symbols and compares Greeks"
• ❌ "Frontend aggregates volume data across expirations"
• ❌ "Frontend calculates moving averages from price history"

After v3.0.0, the framework forces explicit architectural decisions:

• ✅ "Backend includes P/C ratio in response payload"
• ✅ "Backend multi-symbol comparison endpoint returns normalized comparison data"
• ✅ "Backend includes aggregated volume metrics in expiration summary"
• ✅ "Backend includes SMA-20/50/200 in market data response"

---

🎁 Impact on AI-Generated PRDs

Teams adopting v3.0.0 gain:

• Consistency: All PRDs follow "Smart Backend, Simple Frontend" principle
• Future-Proofing: Backend APIs designed to support future clients (mobile, desktop, API consumers)
• Performance: Heavy computations happen on backend, not repeated in every client
• Maintainability: Business logic in one place, not duplicated across frontend components
• Security: Security-sensitive operations explicitly assigned to backend
• DRY Principle: Data transformations happen once on backend, not repeatedly on each client

---

📚 Framework Philosophy

"Smart Backend, Simple Frontend": Business logic and calculations belong on backend; frontend focuses on presentation and UX.

"Backend-First Thinking": For data features, start by designing the ideal API response, then build frontend to consume it.

"Single Source of Truth": Data transformations happen once on backend, not repeatedly on each client.

---

🔧 Breaking Changes

1. PRD Format: Functional requirements now require [Backend/Frontend] prefix
2. PRD Structure: "Architectural Decisions" section now mandatory in both Quick Start and Full PRD
3. File Locations: Active PRDs move from /documentation/ to /documentation/specifications/active/
4. Decision Process: Step 3 of Application Process now requires architectural verification
5. Examples Format: All examples updated to show architectural separation

---

📖 Migration Guide

From v2.x to v3.0.0:

1. Functional Requirements Format Change: Update all functional requirements to use architectural prefix

   • Old: FR1: The system must calculate P/C ratios
   • New: FR1: Backend: Calculate P/C ratios during options chain processing

2. Add Architectural Decisions Section: All PRDs now require explicit architectural decisions section before functional requirements

3. Apply Decision Framework: For each requirement, answer the 5 questions to determine placement

4. Run Architectural Audit: Before finalizing PRD, verify checklist and check for red flags

5. Update Examples: Review existing PRDs for frontend calculations, aggregations, or multi-step API calls and refactor to backend

---

✨ Real-World Validation

This framework was developed after observing systematic mistakes in AI-generated PRDs across multiple projects:

• Options trading platforms putting Greeks calculations in React components
• Multi-symbol comparison features making parallel frontend API calls
• Volume aggregation happening in browser instead of Lambda functions
• Moving average calculations duplicated across web and potential mobile clients

The architectural framework eliminates these patterns before implementation begins, saving days of refactoring.

---

🔗 Resources

• Complete CHANGELOG
• Frontend Feature Specification Guidelines
• Framework Documentation

---

Full Changelog: v2.0.0...v3.0.0

v2.0.0 - Framework Completion: Complete 4-Guideline System with ARCHIVAL PROTOCOL

Framework Completion Release

Version 2.0.0 marks the completion of the Specification Generator framework with all four essential guidelines now present and fully integrated.

What's New

Fourth Essential Guideline Added

• implementation-tasks-creation-guidelines.md completes the framework
• Contains the critical ARCHIVAL PROTOCOL (lines 13-61) for systematic completion workflow
• Granular task breakdown methodology with over-engineering prevention
• Interactive check-in process for high-level plan approval
• Domain-specific testing approaches (Backend: Node.js native, Frontend: Vitest + RTL)
• Three-File Rule and inline-first implementation principles

Consistent Naming Convention

All guidelines now follow the pattern: [descriptor]-[action]-guidelines.md

• backend-feature-specification-guidelines.md
• frontend-feature-specification-guidelines.md
• exploratory-feature-specification-guidelines.md
• implementation-tasks-creation-guidelines.md

Complete Workflow Integration

• All PRD guidelines now cross-reference the ARCHIVAL PROTOCOL
• Closed-loop workflow: PRD creation → task generation → implementation → archival
• Prevents systematic archival errors through temporal knowledge gap elimination

Domain-Specific Templates

• New backend-specification-template.md (Lambda/API focus)
• New frontend-specification-template.md (React/TypeScript focus)
• New exploratory-specification-template.md (creative ideation)
• All templates include archival cross-references

Breaking Changes

Guideline Naming Convention Changed:

• Old: guidelines-for-creatively-generating-feature-specifications.md
• New: frontend-feature-specification-guidelines.md or backend-feature-specification-guidelines.md

Repository Structure Reorganized:

• All guidelines now in canonical source repository
• Comprehensive cross-reference system across framework
• Enhanced decision matrix for guideline selection

Migration Guide

From v1.x to v2.0.0:

1. Update guideline references to use new naming convention
2. Use implementation-tasks-creation-guidelines.md for task generation
3. Follow ARCHIVAL PROTOCOL (lines 13-61) with executable verification

See CHANGELOG.md for complete migration details.

Framework Maturity

This release delivers:

• ✅ 4 Essential Guidelines: PRD generation (3) + Task creation (1)
• ✅ Domain-Specific Patterns: Backend, Frontend, Exploratory
• ✅ Testing Standards: Node.js native (Backend), Vitest + RTL (Frontend)
• ✅ Archival Protocol: Systematic completion workflow
• ✅ Consistent Naming: All guidelines follow established pattern
• ✅ Cross-References: Complete integration across framework
• ✅ Real-World Examples: Battle-tested in production

Impact

Teams adopting v2.0.0 gain:

• Complete Framework: All four essential guidelines present
• Systematic Workflow: No gaps from ideation to archival
• Error Prevention: ARCHIVAL PROTOCOL eliminates systematic mistakes
• Consistency: Domain-first organization with clear patterns
• Production-Ready: Battle-tested across multiple repositories

---

Full Changelog: https://github.com/munair/specification-generator/blob/main/CHANGELOG.md#200---monday-november-3-2025

v1.1.0: Real-World Validation with Battle-Tested Examples

What's New

This release contributes to battle-tested nature of the framework. It does so by including more real-world validation and institutionalizing key learnings from actual implementations.

Real-World Example Added

• Persistent Display CSS Grid Solution: Complete feature specification showing UI/UX optimization
• Technical Solution: CSS Grid approach eliminating text wrapping while maintaining accessibility

Framework Evolution

• Feature Tagging Strategy: Institutionalized descriptive tagging approach (persistent-display-css-grid-solution)
• Testing Integration: Guidelines for aligning tests with component structure changes
• Documentation Lifecycle: Complete process from creative exploration to archived specifications

Enhanced Guidelines

• Freeform Guidelines: Added Section 7 with comprehensive tagging strategy and benefits
• Formal Guidelines: Added Section 6 with tagging process and implementation best practices
• Examples README: Updated with new example and framework evolution insights

Why This Matters

This release demonstrates the framework's effectiveness through two battle-tested examples:

1. Budget Filtering (Business Logic) - Complex feature with 5 explicit constraints
2. Persistent Display (UI/UX) - Technical layout optimization with accessibility focus

The first uses the guidelines for creatively generating feature specifications and the second uses the guidelines for freeform feature specification generation.

Framework Maturity

• Battle-tested examples: Real implementations with measurable results
• Proven process: Complete journey from creative exploration to production
• Institutionalized learning: Key patterns and best practices captured
• Adoption readiness: Framework transformed from theoretical to proven methodology

Impact for Teams

Teams adopting this framework now have:

• Concrete examples of different feature types
• Complete implementation journeys to follow
• Institutionalized best practices and tagging strategies
• Additional proof that the approach works in real-world scenarios

What's Included

• examples/feature-specification-persistent-display-css-grid-solution.md - Complete real-world example
• Enhanced guidelines with tagging strategy and implementation best practices
• Framework evolution documentation and lessons learned
• Updated examples README with framework maturity insights

---

Ready to transform your feature specification process? This release provides everything you need to adopt a proven, battle-tested approach to AI-assisted product development.

Quick Start

1. Review the examples: See how the framework solved complex problems
2. Follow the guidelines: Use the enhanced framework for your next feature
3. Apply the learnings: Leverage institutionalized best practices
4. Tag your implementations: Use descriptive tags for future reference

---

This framework is now significantly more compelling for adoption, demonstrating not just theory but proven practice with measurable results.

v1.0.0

Added

• Complete framework for AI-generated feature specifications

  • Guidelines for AI assistants to create comprehensive PRDs
  • Clarifying Questions Framework with prioritized categories
  • PRD Structure templates (Quick Start and Full Process)
  • Guiding Principles including "Creative Abandon Within Scope"

• Manual template approach

  • Simple template for straightforward features (6 sections)
  • Full template for complex features (14 sections + quality checklist)
  • Both templates align perfectly with AI-generated guidelines

• Real-world validation

  • Budget filtering feature specification example
  • Successfully implemented in production with record delivery time
  • Demonstrates framework effectiveness in practice

• Supporting tools

  • Freeform exploration guidelines for creative brainstorming
  • Examples directory with battle-tested specifications
  • Comprehensive documentation and getting started guides

Features

• Two complementary approaches: AI-generated and manual templates
• Boundary-first methodology: "First, build the fence. Then, explore every inch of the playground"
• Scope control: Prevents AI scope creep through structured questioning
• Quality assurance: Built-in testing requirements and success metrics
• Enterprise considerations: Privacy, security, compliance, and audit sections

Documentation

• Clear README with approach comparison table
• Organized repository structure with guidelines/, templates/, and examples/ directories
• Real-world examples showing framework effectiveness
• Professional package metadata and versioning

---