gh-codethread-claude-code-plugins-plugins-spec-dev/skills/spec-architect/references/TECH_SPEC_TEMPLATE.md

[Feature Name] - Implementation Guide

User Sign off: [REQUIRED - DO NOT BUILD WITHOUT THIS]

Implementation Context

What We're Building

[1-2 sentence summary linking to feature.md requirements]

Why This Approach

[High-level rationale for technical direction taken]

Discovery Findings

Similar Implementations

[Reference existing features that solve similar problems - use Explore agent findings]

Pattern: [Pattern Name]

• Implementation: relative-to-cwd/path/to/existing.ext:startLine:endLine
• Follow this pattern for: [what aspects]
• Note: [Key observations about the pattern]

Pattern: [Another Pattern]

• Example: relative-to-cwd/path/to/another.ext:line:col
• Key learning: [What to replicate or avoid]

Key Integration Points

[Where this feature connects to existing code - from Explore agent discoveries]

• [System/Service]: Uses ServiceName from relative-to-cwd/path/to/service.ext:line:col
  • Purpose: [Why we integrate here]
• [Another Integration]: Add to relative-to-cwd/path/to/file.ext:line:col
  • Purpose: [Why we integrate here]

Constraints & Gotchas

[Technical constraints, edge cases, and discoveries from exploration]

• [Constraint or gotcha discovered]
• [Performance limitation or consideration]
• [Security requirement or compliance need]

Technology Decisions

[Decision Area]

Options Considered:

• Option A: [Brief description]
  • Pros: [Key benefits]
  • Cons: [Key drawbacks]
• Option B: [Brief description]
  • Pros: [Key benefits]
  • Cons: [Key drawbacks]

Selected: Option [X]

• Rationale: [Why this choice best serves requirements]
• Documentation: [Link to official docs if helpful]
• Example usage: relative-to-cwd/path/to/similar-usage.ext:line:col

File Map

Files to Create

• relative-to-cwd/path/to/new/file.ext:1:1 - [Component purpose and responsibility]
• relative-to-cwd/path/to/another/new.ext:1:1 - [Component purpose]

Files to Modify

• relative-to-cwd/path/to/existing.ext:line:col - [What needs to change and why]
• relative-to-cwd/path/to/another.ext:line:col - [What needs to change]

Files to Reference

[Files that provide patterns, types, or examples to follow]

• relative-to-cwd/path/to/pattern.ext - [What pattern/approach to follow]
• relative-to-cwd/path/to/types.ext - [Type patterns to replicate]

Component Architecture

Component: [Component Name]

Responsibility: [What this component does - high level, not implementation details]

Interfaces With:

• Uses: relative-to-cwd/path/to/dependency.ext:line:col - [Why and how it's used]
• Provides: [What other components will consume from this]

Key Constraints:

• [Performance requirements from NFRs]
• [Security requirements from NFRs]
• [Other constraints discovered during planning]

Testing Approach:

• Follow pattern: relative-to-cwd/path/to/similar/test.ext:line:col
• Use: [Testing tools/skills - playwright-skill, API helpers, etc.]
• Focus: [What aspects are critical to test]

Component: [Another Component]

[Repeat structure above for each major component]

Implementation Tasks

Component: [Component Name]

Location: relative-to-cwd/path/to/component/directory

• COMP-1: [Task description] (delivers FR-X, NFR-Y) [TESTABLE]

  • Create: relative-to-cwd/path/to/new/file.ext:1:1
  • Reference pattern: relative-to-cwd/path/to/existing/similar.ext:line:col
  • Integration: Uses [ServiceName] from relative-to-cwd/path/to/service.ext:line:col

• COMP-2: [Task description] (delivers FR-X) [TESTABLE]

  • Modify: relative-to-cwd/path/to/existing/file.ext:line:col
  • Follow pattern from COMP-1
  • Dependencies: COMP-1 must be complete

Component: [Another Component] [TEST AFTER COMPONENT]

Location: relative-to-cwd/to/another/component

• AUTH-1: [Task description] (delivers FR-1, NFR-3)

  • Create: relative-to-cwd/to/auth/service.ts:1:1
  • Reference: relative-to-cwd/to/existing/auth-pattern.ts:23:67

• AUTH-2: [Task description] (delivers FR-2)

  • Update: relative-to-cwd/to/session/manager.ts:45:12
  • Dependencies: AUTH-1 must be complete before AUTH-2

Note: Test AUTH-1 and AUTH-2 together after both are implemented

Testing Guidance

Testing Setup

[Reference to Testing Setup section in feature.md - spec-tester will use this]

See feature.md "Testing Setup" section for system startup, environment requirements, test data, access points, and cleanup procedures.

Testing Patterns to Follow

Unit tests:

• Pattern: relative-to-cwd/path/to/unit.test.ext:line:col
• Focus: [What to test at unit level]

Integration tests:

• Pattern: relative-to-cwd/path/to/integration.test.ext:line:col
• Focus: [What to test at integration level]

E2E tests:

• Tools: [playwright-skill / API helpers / etc.]
• Pattern: relative-to-cwd/path/to/e2e.test.ext:line:col

Testing Tools Available

[List testing tools, scripts, or helpers available for this feature]

• Jest/Vitest for unit and integration tests
• playwright-skill for UI testing (spec-tester can load this)
• API test helpers: scripts/test-api.sh
• [Other tools discovered during exploration]

Implementation Notes

Discovered During Planning

[Technical discoveries, constraints, gotchas from Explore/researcher agents]

• [Finding from exploration that affects implementation]
• [Constraint discovered that wasn't obvious initially]
• [Best practice from similar implementations]

Migration Strategy

[If this involves breaking changes to PUBLIC APIs]

• [How existing consumers will be supported]
• [Deprecation timeline if applicable]
• [Communication plan for breaking changes]

Note: Internal APIs can be refactored freely without migration strategy.

Performance Considerations

[Specific NFRs and validation approach]

• NFR-X requires: [Specific performance target]
• Validate with: [How to measure/verify]

Security Considerations

[Authentication, authorization, data protection, compliance]

• [Specific security requirements from NFRs]
• [Compliance requirements if applicable]
• [Security patterns to follow from similar features]

References

Codebase Documentation

[Links to relevant documentation within the repository]

• [Internal docs about patterns/architecture]
• [ADRs (Architecture Decision Records) if applicable]

External Documentation

[Links to API docs, library docs, frameworks]

• [Library/framework documentation]
• [API documentation for external services]

Related Specifications

[Links to related feature.md files in specs/]

• specs/XXX-related-feature/feature.md - [How it relates]

Technical Debt Considerations

[Known compromises and future refactoring needs identified during planning]

• [Known shortcut or compromise with rationale]
• [Future improvement opportunity]

Dependencies and Prerequisites

[External services, libraries, infrastructure requirements]

• [External service dependencies]
• [Library/framework versions required]
• [Infrastructure or environment requirements]

Regressions or Missed Requirements

None found