implementation-planning

name	Implementation Planning
description	Create technical implementation plans from specifications with intelligence-backed architectural decisions. Use when specification exists and user mentions tech stack, architecture, implementation approach, or asks "how to implement" or "how to build" the feature.
degree-of-freedom	medium
allowed-tools	Bash(project-intel.mjs:*), Read, Write, Edit

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

Implementation Planning

Purpose: Transform technology-agnostic specifications into technical implementation plans with architecture decisions, tech stack selection, and acceptance criteria mapping.

Constitutional Authority: Article IV (Specification-First Development), Article VI (Simplicity & Anti-Abstraction), Article I (Intelligence-First Principle)

---

Phase 0: Pre-Design Constitutional Gates

MANDATORY: Check Article VI limits BEFORE design.

Step 0.1: Validate Specification Exists

PreToolUse hook will block plan.md creation without spec.md, but verify explicitly:

FEATURE=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "${SPECIFY_FEATURE:-}")
if [[ ! -f "specs/$FEATURE/spec.md" ]]; then
    echo "ERROR: Cannot create plan without specification (Article IV violation)"
    echo "Next: Run specify-feature skill or use /feature command"
    exit 1
fi

Step 0.2: Constitution Check (Article VI)

Read specification and assess complexity:

Gate 1: Project Count

• Maximum 3 projects for initial implementation
• If spec implies 4th project → require justification

Gate 2: Abstraction Layers

• Maximum 2 abstraction layers per concept
• No repository/service/facade patterns without documented need

Gate 3: Framework Trust

• Use framework features directly (no wrappers)
• Justify any custom implementations

If violations detected, create Complexity Justification section:

Violation	Why Needed	Simpler Alternative Rejected Because
[e.g., 4th project]	[reason]	[why 3 projects insufficient]

---

Phase 1: Intelligence-First Context Gathering

Article I Mandate: Query before reading files.

Step 1.1: Search for Existing Patterns

!`project-intel.mjs --search "<tech-stack-keywords>" --type "tsx,ts,py,go" --json > /tmp/plan_intel_patterns.json`

Example:

• If spec mentions "authentication" → search for "auth login session"
• If spec mentions "real-time" → search for "websocket socket io"

Save evidence to /tmp/plan_intel_patterns.json

Step 1.2: Analyze Project Architecture

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

Understand:

• Existing tech stack and frameworks
• Directory structure patterns
• Naming conventions
• Test frameworks in use

Step 1.3: Query Dependencies and Integration Points

!`project-intel.mjs --dependencies "<key-files>" --direction both --json > /tmp/plan_intel_deps.json`

Identify integration points where new feature connects to existing code.

---

Phase 2: Technical Design

Step 2.1: Select Tech Stack

Based on intelligence findings and spec requirements:

Language/Version: [from project-intel overview or specify new] Primary Dependencies: [frameworks, libraries with versions] Storage: [database, caching, file system if applicable] Testing: [test frameworks, assertion libraries] Target Platform: [web, mobile, desktop, server]

CoD^Σ Evidence:

Tech Stack Selection:
project-intel.mjs --overview → existing stack is TypeScript + React + Supabase
Decision: Continue with existing stack for consistency
Evidence: src/*/package.json:12 shows react@18, typescript@5

Step 2.2: Design Architecture

Component Breakdown (from spec user stories):

For each P1 user story:

1. Identify required components (models, services, UI, API)
2. Map to existing architecture (from intelligence queries)
3. Document new components needed
4. Define interfaces/contracts

Example:

User Story P1: Email/Password Authentication

Components:
- Model: User (extends existing User model at models/user.ts:8)
- Service: AuthService (new, will integrate with existing auth.ts:23)
- API: POST /auth/login, POST /auth/register (new endpoints)
- UI: LoginForm, RegisterForm (enhance existing at components/auth/)

Integration Points:
- Existing: src/utils/auth.ts:23 (session management)
- New: src/services/auth-service.ts (authentication logic)

Step 2.3: Create Research Document

Generate research.md with:

Technical Decisions:

1. Decision: [what was decided]
   • Rationale: [why]
   • Alternatives considered: [what else was considered]
   • Evidence: [file:line from intelligence or MCP query]

Example:

## Decision 1: OAuth Provider Libraries

Decision: Use @supabase/auth-helpers for OAuth integration

Rationale:
- Already using Supabase for backend (src/lib/supabase.ts:5)
- Native support for Google/GitHub OAuth
- Handles token refresh automatically

Alternatives Considered:
- NextAuth.js: Rejected (adds complexity, not needed with Supabase)
- Custom OAuth: Rejected (reinventing wheel, Article VI violation)

Evidence:
- Intelligence: project-intel found Supabase client at src/lib/supabase.ts:5
- MCP Ref: @supabase/auth-helpers supports Google/GitHub OAuth

Step 2.4: Design Data Model

Generate data-model.md (entities WITHOUT implementation):

For each entity:

• Name and purpose
• Attributes (without database types)
• Relationships to other entities
• Validation rules

Example:

## Entity: User

Purpose: Represents authenticated system user

Attributes:
- id: Unique identifier
- email: Email address (unique, validated)
- password_hash: Hashed password (never plaintext)
- oauth_provider: Optional (google|github)
- oauth_id: Optional provider-specific ID
- created_at: Registration timestamp
- last_login: Last successful login

Relationships:
- Has many: Sessions
- Has many: UserRoles

Validation:
- email: Must be valid email format
- password: Minimum 8 characters, must include number + special char
- oauth_provider + oauth_id: Required together or both null

Step 2.5: Define API Contracts

Generate contracts/ directory with API specifications:

For each endpoint:

• HTTP method and path
• Request schema
• Response schema
• Error cases
• Authentication required?

Example: contracts/auth-endpoints.md

## POST /api/auth/register

Purpose: Create new user account

Request:
- email: string (required, valid email)
- password: string (required, min 8 chars)

Response (201 Created):
- user: { id, email, created_at }
- session: { access_token, refresh_token, expires_at }

Errors:
- 400: Invalid email format
- 409: Email already exists
- 500: Server error

Authentication: None (public endpoint)

Step 2.6: Create Quickstart Validation Scenarios

Generate quickstart.md with test scenarios:

For each user story, document:

• Setup steps
• Exact actions to test
• Expected outcomes
• How to verify success

Example:

## Scenario 1: User Registration (P1 Story)

Setup:
1. Navigate to /register
2. Have valid email ready

Test Steps:
1. Enter email: [e-mail]
2. Enter password: SecurePass123!
3. Click "Register"

Expected Outcome:
- HTTP 201 response
- User created in database
- Session token returned
- Redirected to /dashboard

Verification:
- Check database: SELECT * FROM users WHERE email='[e-mail]'
- Check session storage: localStorage.getItem('session')
- Verify redirect: window.location.pathname === '/dashboard'

---

Phase 3: Acceptance Criteria Mapping

Article III Requirement: Minimum 2 testable ACs per user story.

Step 3.1: Extract User Stories from Specification

Read specs/$FEATURE/spec.md

Identify all user stories with priorities (P1, P2, P3).

Step 3.2: Generate Acceptance Criteria

For EACH user story, create ≥2 ACs:

AC Format:

• AC-ID: [Story]-[Number] (e.g., P1-001, P1-002)
• Given [precondition], When [action], Then [outcome]
• Test: How to automate verification

Example:

### User Story P1: Email/Password Registration

**AC-P1-001**: User can register with valid email and password
- **Given** user has valid email and strong password
- **When** user submits registration form
- **Then** account is created and user is logged in
- **Test**: POST /api/auth/register with valid data returns 201 + session token

**AC-P1-002**: System rejects weak passwords
- **Given** user has valid email but weak password ("12345")
- **When** user submits registration form
- **Then** registration fails with error "Password must be at least 8 characters with number and special character"
- **Test**: POST /api/auth/register with weak password returns 400 with specific error

---

Phase 4: Post-Design Constitutional Re-Check

Article VI Mandate: Verify gates still pass after design.

Step 4.1: Re-validate Complexity

Check if design introduced violations:

• Did component breakdown create 4th project?
• Did architecture add unnecessary abstraction layers?
• Did design create wrappers around framework features?

If new violations: Update Complexity Justification table.

Step 4.2: Verify Framework Trust

Confirm design uses framework features directly:

• Authentication: Using Supabase Auth (not custom)
• Database: Using Supabase client (not ORM wrapper)
• State management: Using framework state (not custom abstraction)

---

Phase 5: Generate Implementation Plan

Step 5.1: Write plan.md

Use @.claude/templates/plan.md structure:

---
feature: <number>-<name>
created: <YYYY-MM-DD>
specification: specs/<number>-<name>/spec.md
status: Ready for Implementation
---

Sections:

1. Summary: One paragraph overview
2. Technical Context: Tech stack, platform, dependencies
3. Constitution Check: Gates passed/violated with justifications
4. Architecture: Component breakdown with integration points
5. Acceptance Criteria: All ACs from Step 3.2
6. File Structure: Exact paths where code will live
7. CoD^Σ Evidence: Intelligence query results, MCP sources

Save:

• specs/$FEATURE/plan.md
• specs/$FEATURE/research.md
• specs/$FEATURE/data-model.md
• specs/$FEATURE/contracts/*.md
• specs/$FEATURE/quickstart.md

Step 5.2: Report Completion

Output:

✓ Implementation plan created: specs/<number>-<name>/plan.md

Intelligence Evidence:
- project-intel.mjs queries: 3 executed, results in /tmp/plan_intel_*.json
- Existing patterns found: auth.ts:23, Login.tsx:12
- Integration points: 2 identified

Technical Decisions:
- Tech stack: TypeScript + React + Supabase (existing)
- New components: AuthService, LoginForm, RegisterForm
- Architecture: Extends existing auth pattern

Artifacts Generated:
- plan.md (implementation plan)
- research.md (technical decisions)
- data-model.md (User entity)
- contracts/auth-endpoints.md (API specs)
- quickstart.md (test scenarios)

Acceptance Criteria: 6 total (2 per P1 story)

Constitutional Compliance:
- ✓ Article I: Intelligence queries executed before design
- ✓ Article IV: Plan references existing spec.md
- ✓ Article VI: No complexity violations (3 projects, framework trust maintained)
- ✓ Article III: All user stories have ≥2 ACs

**Automatic Task Generation**:
Now invoking generate-tasks skill to create task breakdown...

[Task generation and audit will proceed automatically]

---

Phase 6: Automatic Task Generation

DO NOT ask user to trigger task generation - this is automatic workflow progression.

Step 6.1: Invoke generate-tasks Skill

After all plan artifacts are complete (plan.md, research.md, data-model.md, contracts/, quickstart.md), automatically proceed to task generation.

Instruct Claude:

"Now that the implementation plan is complete, automatically generate the task breakdown:

Use the generate-tasks skill to create tasks.md.

This will:

1. Load user stories from specs/$FEATURE/spec.md
2. Load technical details from specs/$FEATURE/plan.md
3. Organize tasks by user story (Article VII)
4. Mark parallelizable tasks with [P]
5. Ensure ≥2 ACs per story (Article III)
6. Automatically invoke /audit for quality gate validation

The generate-tasks skill will handle this entire workflow automatically, including the quality gate check."

Step 6.2: Quality Gate Enforcement

The generate-tasks skill will automatically invoke /audit after creating tasks.md.

This enforces:

• Article IV: Specification-First Development (spec → plan → tasks validated)
• Article V: Template-Driven Quality (automatic validation)
• Article VII: User-Story-Centric Organization (verified)

User will see:

• tasks.md created
• /audit runs automatically
• Quality gate PASS/FAIL result
• Next steps based on audit outcome

No manual intervention required - workflow proceeds automatically through task generation and validation.

---

Note: This completes the planning phase. The next steps (task generation + audit) happen automatically.

---

## Anti-Patterns to Avoid

**DO NOT**:
- Plan before specification exists (Article IV violation)
- Skip intelligence queries (Article I violation)
- Design without checking constitution gates (Article VI violation)
- Create ACs with < 2 per story (Article III violation)
- Mix specification and implementation concerns
- Copy existing code without intelligence analysis
- Create wrapper layers around framework features

**DO**:
- Query intelligence sources before designing
- Check constitution gates pre AND post design
- Create ≥2 testable ACs per user story
- Use CoD^Σ traces with file:line evidence
- Trust framework features (avoid custom implementations)
- Document decisions with rationale in research.md
- Map components to existing architecture patterns

---

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