@.claude/shared-imports/constitution.md @.claude/shared-imports/CoD_Σ.md @.claude/templates/feature-spec.md

Specification Creation

Purpose: Generate technology-agnostic feature specifications (WHAT/WHY only, no HOW) with intelligence-backed evidence and structured user stories.

Constitutional Authority: Article IV (Specification-First Development), Article I (Intelligence-First Principle), Article II (Evidence-Based Reasoning)

Phase 1: Intelligence-First Context Gathering

MANDATORY: Execute intelligence queries BEFORE any file operations.

Step 1.1: Auto-Number Next Feature

bash

!`fd --type d --max-depth 1 '^[0-9]{3}-' specs/ 2>/dev/null | sort | tail -1`

Extract highest existing feature number, increment by 1 for next feature.

Example:

•Last feature: specs/003-auth-system
•Next number: 004

Step 1.2: Query Existing Patterns

bash

!`project-intel.mjs --search "<user-keywords>" --type md --json > /tmp/spec_intel_patterns.json`

Search for related features, similar requirements, existing patterns.

Save evidence to /tmp/spec_intel_patterns.json for CoD^Σ tracing.

Step 1.3: Understand Project Architecture

bash

!`project-intel.mjs --overview --json > /tmp/spec_intel_overview.json`

Get project structure, tech stack, existing components to inform requirements.

Phase 2: Extract User Requirements (WHAT/WHY Only)

Article IV Mandate: Specifications MUST be technology-agnostic.

Step 2.1: Problem Statement

Extract from user description:

•What problem are they trying to solve?
•Why is this needed?
•Who will use this?
•What value does it provide?

NO IMPLEMENTATION DETAILS: No tech stack, no architecture, no "how to build it".

Step 2.2: User Stories with Priorities

Organize requirements as user stories:

Format:

code

## User Story 1 - [Title] (Priority: P1)

**As a** [user type]
**I want to** [capability]
**So that** [value/benefit]

**Why P1**: [Rationale for priority]

**Independent Test**: [How to validate this story works standalone]

**Acceptance Scenarios**:
1. **Given** [state], **When** [action], **Then** [outcome]
2. **Given** [state], **When** [action], **Then** [outcome]

Priority Levels:

•P1: Must-have for MVP (core value)
•P2: Important but not blocking (enhances P1)
•P3: Nice-to-have (can be deferred)

Requirement: Each story MUST be independently testable (Article VII).

Step 2.3: Functional Requirements (Technology-Agnostic)

Document as testable requirements:

code

- **FR-001**: System MUST [specific capability]
- **FR-002**: Users MUST be able to [interaction]
- **FR-003**: System MUST [behavior]

Mark Unknowns:

code

- **FR-004**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified]

Maximum 3 [NEEDS CLARIFICATION] markers - use sparingly, clarify rest through user dialogue.

Phase 3: Generate Specification with CoD^Σ Evidence

Step 3.1: Create Feature Directory Structure

bash

NEXT_NUM=$(printf "%03d" $(($(fd --type d --max-depth 1 '^[0-9]{3}-' specs/ 2>/dev/null | wc -l) + 1)))
FEATURE_NAME="<derived-from-user-description>"  # Lowercase, hyphenated, 2-4 words
mkdir -p specs/$NEXT_NUM-$FEATURE_NAME

Step 3.2: Create Git Branch (if git repo)

bash

if git rev-parse --git-dir >/dev/null 2>&1; then
    git checkout -b "$NEXT_NUM-$FEATURE_NAME"
fi

Step 3.3: Write Specification

Use @.claude/templates/feature-spec.md structure with:

•

YAML Frontmatter:

yaml

---
feature: <number>-<name>
created: <YYYY-MM-DD>
status: Draft
priority: P1
---

•
Problem Statement: What problem are we solving and why?
•
User Stories: From Step 2.2 (prioritized, independently testable)
•
Functional Requirements: From Step 2.3 (technology-agnostic)
•
Success Criteria: Measurable outcomes (not technical metrics)

•

CoD^Σ Evidence Trace:

code

Intelligence Queries:
- project-intel.mjs --search "<keywords>" → /tmp/spec_intel_patterns.json
  Findings: [file:line references to similar features]
- project-intel.mjs --overview → /tmp/spec_intel_overview.json
  Context: [existing architecture patterns]

Assumptions:
- [ASSUMPTION: rationale based on intelligence findings]

Clarifications Needed:
- [NEEDS CLARIFICATION: specific question]

•
Edge Cases: Boundary conditions, error scenarios

Step 3.4: Save Specification

bash

Write specs/$NEXT_NUM-$FEATURE_NAME/spec.md

Phase 4: Report to User

Output Format:

code

✓ Feature specification created: specs/<number>-<name>/spec.md

Intelligence Evidence:
- Queries executed: project-intel.mjs --search, --overview
- Patterns found: <file:line references>
- Related features: <existing feature numbers>

User Stories:
- P1 stories: <count> (MVP scope)
- P2 stories: <count> (enhancements)
- P3 stories: <count> (future)

Clarifications Needed:
- [NEEDS CLARIFICATION markers if any, max 3]

**Automatic Next Steps**:
1. If clarifications needed: Use clarify-specification skill
2. Otherwise: **Automatically create implementation plan**

Invoking /plan command now...

[Plan creation, task generation, and audit will proceed automatically]

Phase 5: Automatic Implementation Planning

DO NOT ask user to trigger planning - this is automatic workflow progression (unless clarifications needed).

Step 5.1: Check for Clarifications

If [NEEDS CLARIFICATION] markers exist:

•Do NOT proceed to planning
•Report clarifications needed to user
•User must run clarify-specification skill or provide answers
•After clarifications, re-run specify-feature skill

If NO clarifications (or max 0-1 minor ones):

•Proceed automatically to implementation planning

Step 5.2: Invoke /plan Command

Instruct Claude:

"Specification is complete. Automatically create the implementation plan:

Run: /plan specs/$FEATURE/spec.md

This will:

•Create implementation plan with tech stack selection
•Generate research.md, data-model.md, contracts/, quickstart.md
•Define ≥2 acceptance criteria per user story
•Automatically invoke generate-tasks skill
•Automatically invoke /audit quality gate

The entire workflow from planning → tasks → audit happens automatically. No manual intervention needed."

Step 5.3: Workflow Automation

After /plan is invoked, the automated workflow proceeds:

code

/plan specs/$FEATURE/spec.md
  ↓ (automatic)
create-implementation-plan skill
  ↓ (automatic)
generate-tasks skill
  ↓ (automatic)
/audit $FEATURE
  ↓
Quality Gate Result: PASS/FAIL

User sees:

•spec.md created ✓
•plan.md created ✓
•tasks.md created ✓
•audit report generated ✓
•Implementation readiness status

User only needs to:

•Review audit results
•Fix any CRITICAL issues (if audit fails)
•Or proceed with /implement plan.md (if audit passes)

Note: This completes specification creation. Next steps happen automatically unless clarifications are needed.

code


**Constitutional Compliance**:
- ✓ Article I: Intelligence queries executed before file operations
- ✓ Article II: CoD^Σ trace with evidence saved to /tmp/*.json
- ✓ Article IV: Specification is technology-agnostic (WHAT/WHY only)
- ✓ Article VII: User stories are independently testable

---

## Anti-Patterns to Avoid

**DO NOT**:
- Include tech stack choices in specification
- Design architecture or data models
- Specify implementation details ("use React hooks", "create API endpoint")
- Create more than 3 [NEEDS CLARIFICATION] markers (clarify through dialogue first)
- Write vague requirements ("system should be fast" → specify "p95 latency < 200ms")

**DO**:
- Focus on user value and business requirements
- Make requirements testable and measurable
- Prioritize user stories (P1, P2, P3)
- Document evidence from intelligence queries
- Limit unknowns (max 3 [NEEDS CLARIFICATION])

---

## Example Execution

**User Input**: "I want to build a user authentication system with social login options"

**Execution**:

1. **Intelligence Queries**:
   ```bash
   fd --type d --max-depth 1 '^[0-9]{3}-' specs/
   # Output: specs/001-dashboard, specs/002-api, specs/003-reporting
   # Next: 004

   project-intel.mjs --search "auth login" --type tsx --json
   # Findings: src/components/Login.tsx:12-45 (existing login form)
   #           src/utils/auth.ts:23 (auth helper functions)

•

Extract Requirements:

code

Problem: Users need to securely access their accounts
Why: Enable personalized experiences and data security
Who: End users, administrators
Value: Secure access, convenience

User Stories:
- P1: Basic email/password authentication
- P2: Social login (Google, GitHub)
- P3: Two-factor authentication

•

Create Feature:

bash

mkdir -p specs/004-user-authentication
git checkout -b 004-user-authentication

•
Write Spec with CoD^Σ evidence, user stories, requirements

•

Report:

code

✓ Feature specification created: specs/004-user-authentication/spec.md

Intelligence Evidence:
- Found existing: src/components/Login.tsx:12-45, src/utils/auth.ts:23
- Pattern: Email/password already partially implemented

User Stories: 3 total (1 P1, 1 P2, 1 P3)

Next: Run clarify-specification skill or create-implementation-plan skill

Skill Version: 1.0.0 Last Updated: 2025-10-19