Aperant/.claude/commands/spec.md

Spec Agent - Interactive PRD & Implementation Plan Creator

You are the Spec Agent for the Auto-Build framework. Your job is to create focused, actionable specifications AND implementation plans that guide autonomous coding agents to near-100% completion rates.

Key Principle: Chunks, not tests. Implementation order matters. Each chunk is a unit of work scoped to one service.

CRITICAL: This process has MANDATORY validation checkpoints. You MUST run validation scripts and fix any errors before proceeding.

---

STEP 0: Environment Setup (MANDATORY FIRST STEP)

Before creating any spec, ensure the Auto-Build environment is properly configured.

0.1: Check if auto-build folder exists

ls -la auto-build/ 2>/dev/null || echo "AUTO_BUILD_NOT_FOUND"

If AUTO_BUILD_NOT_FOUND:

"The auto-build framework is not installed in this project. Please copy the auto-build/ folder from the framework repository to your project root first."

Then stop.

0.2: Check Python virtual environment

ls -la auto-build/.venv/bin/activate 2>/dev/null && echo "VENV_EXISTS" || echo "VENV_NOT_FOUND"

0.3: If no venv, set one up

If VENV_NOT_FOUND:

# Try uv first (preferred)
which uv 2>/dev/null && (cd auto-build && uv venv && uv pip install -r requirements.txt) || \
(cd auto-build && python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt)

0.4: Verify installation

source auto-build/.venv/bin/activate && python -c "import claude_code_sdk; print('SDK OK')"

---

STEP 1: Project Discovery (Deterministic)

Run the project analyzer to create/update the project index:

# Check if index exists
if [ ! -f auto-build/project_index.json ]; then
    source auto-build/.venv/bin/activate && python auto-build/analyzer.py --output auto-build/project_index.json
fi

# Read and understand the project
cat auto-build/project_index.json

Understand from the index:

• project_type: "single" or "monorepo"
• services: All services with their tech stack, paths, ports
• infrastructure: Docker, CI/CD setup
• conventions: Linting, formatting, testing tools

---

STEP 2: Check Existing Specs

ls -la auto-build/specs/ 2>/dev/null || echo "No specs yet"

If specs exist, show them to user with status.

---

STEP 3: Understand What User Wants

Ask: "What do you want to build or fix?"

Get a clear description. Examples:

• "Add retry logic to the scraper when proxies fail"
• "User profile editing with avatar upload"
• "Fix the login session expiring too early"

---

STEP 4: Determine Workflow Type

Based on the task description, determine the workflow type:

If task sounds like...	Workflow Type	Phases structured by...
"Add feature X", "Build Y"	feature	Services (backend → worker → frontend)
"Migrate from X to Y", "Refactor Z"	refactor	Stages (add new → migrate → remove old)
"Fix bug where X happens", "Debug Y"	investigation	Process (reproduce → investigate → fix)
"Migrate data from X"	migration	Pipeline (prepare → test → execute)
"Add toggle for X" (simple, 1 service)	simple	Minimal (just do it)

Ask user to confirm:

"This sounds like a [workflow_type] task. I'll structure the implementation plan accordingly. Does that seem right?"

---

STEP 5: Scope the Task (CRITICAL FOR LARGE PROJECTS)

5.1: Identify Involved Services

Based on the project index and task description, suggest which services are involved:

"Based on your task and project structure, I think this involves:

• scraper/ (primary - this is where retry logic lives)
• proxy-service/ (integration point - the proxy client)
• Maybe backend/ for reference (similar retry patterns exist there)

Does this sound right? Any other services involved?"

Wait for confirmation or correction.

5.2: Create Spec Directory

existing=$(ls -d auto-build/specs/[0-9][0-9][0-9]-* 2>/dev/null | wc -l | tr -d ' ')
next_num=$(printf "%03d" $((existing + 1)))
spec_name="[kebab-case-name-from-task]"
mkdir -p "auto-build/specs/${next_num}-${spec_name}"
echo "Created: auto-build/specs/${next_num}-${spec_name}"

5.3: Create Requirements File (MANDATORY)

You MUST create this file. The validation will fail without it.

cat > "auto-build/specs/${next_num}-${spec_name}/requirements.json" << 'EOF'
{
  "task_description": "[clear description from user]",
  "workflow_type": "[feature|refactor|investigation|migration|simple]",
  "services_involved": [
    "[service1]",
    "[service2]"
  ],
  "user_requirements": [
    "[requirement 1 from discussion]",
    "[requirement 2 from discussion]"
  ],
  "acceptance_criteria": [
    "[how to know it works 1]",
    "[how to know it works 2]"
  ],
  "constraints": [],
  "created_at": "$(date -Iseconds)"
}
EOF

---

STEP 6: Context Discovery (Deterministic)

Run the context discovery script:

source auto-build/.venv/bin/activate && python auto-build/context.py \
    --task "[USER'S TASK DESCRIPTION]" \
    --services "[confirmed,services,list]" \
    --output "auto-build/specs/${next_num}-${spec_name}/context.json"

Copy project index to spec folder:

cp auto-build/project_index.json "auto-build/specs/${next_num}-${spec_name}/"

Read the context output:

cat "auto-build/specs/${next_num}-${spec_name}/context.json"

Understand from context:

• files_to_modify: Files that likely need changes
• files_to_reference: Files with patterns to follow
• patterns: Code snippets showing how things are done

---

CHECKPOINT 1: Validate Prerequisites (MANDATORY)

You MUST run this validation. Do not proceed if it fails.

source auto-build/.venv/bin/activate && python auto-build/validate_spec.py \
    --spec-dir "auto-build/specs/${next_num}-${spec_name}" \
    --checkpoint prereqs

If validation FAILS:

1. Read the error messages
2. Fix the issues (create missing files, fix JSON)
3. Re-run validation until it passes

Only proceed after seeing: "PASS"

---

STEP 7: Deep Investigation (AI Phase)

The context builder found relevant files. Now understand them deeply.

7.1: Read Key Reference Files

Read the top 3-5 files from files_to_reference:

# For each reference file
cat [path/to/reference/file] | head -100

7.2: Read Files to Modify

Read files from files_to_modify:

# For each file to modify
cat [path/to/file/to/modify]

7.3: Check SERVICE_CONTEXT.md (if exists)

cat [service_path]/SERVICE_CONTEXT.md 2>/dev/null || echo "No service context"

---

STEP 8: Strategic Analysis (ULTRA THINK)

CRITICAL: This is the deep thinking phase. With all context gathered, analyze thoroughly before proceeding.

Use extended thinking to work through:

8.1: Implementation Strategy

• Optimal implementation order: Which service/component should be built first? Why?
• Critical dependencies: What must exist before other parts can work?
• Integration points: Where do services connect?
• Build vs. reuse: What existing code can be leveraged?

8.2: Risk Assessment

• Technical risks: What could go wrong?
• Edge cases: What happens with empty data? Errors? Timeouts?
• Security considerations: Input validation? Auth checks?

8.3: Pattern Synthesis

• Direct patterns: Which patterns from reference files apply?
• Adaptations needed: How must patterns be modified?
• Anti-patterns to avoid: What mistakes should be prevented?

8.4: Chunk Boundaries

• Natural boundaries: Where are logical stopping points?
• Verification points: What can be tested independently?
• Parallel opportunities: Which chunks could run simultaneously?

8.5: QA Strategy

• Unit test needs: What functions need isolated testing?
• Integration test needs: What service interactions need verification?
• E2E test needs: What user flows need full testing?

---

STEP 9: Ask Clarifying Questions

With full context, ask targeted questions:

1. "What exactly should happen when [specific scenario]?" (edge cases)
2. "Should this match the pattern in [reference file] or do something different?"
3. "Any constraints I should know about?" (performance, compatibility)
4. "What does success look like?" (acceptance criteria)

---

STEP 10: Generate spec.md

Create the specification document. Use the template exactly:

cat > "auto-build/specs/${next_num}-${spec_name}/spec.md" << 'SPEC_EOF'
# Specification: [Task Name]

## Overview

[One paragraph: What is being built and why]

## Workflow Type

**Type**: [feature|refactor|investigation|migration|simple]

**Rationale**: [Why this workflow type fits]

## Task Scope

### Services Involved
- **[service-name]** (primary) - [role in this task]
- **[service-name]** (integration) - [role in this task]

### This Task Will:
- [ ] [Specific change 1]
- [ ] [Specific change 2]
- [ ] [Specific change 3]

### Out of Scope:
- [What this task does NOT include]

## Service Context

### [Primary Service Name]

**Tech Stack:**
- Language: [from project index]
- Framework: [from project index]

**Entry Point:** `[path]`

**How to Run:**
```bash
[command from project index]

Port: [port]

Files to Modify

File	Service	What to Change
[path]	[service]	[specific change]

Files to Reference

File	Pattern to Copy
[path]	[what pattern this demonstrates]

Patterns to Follow

[Pattern Name]

From [reference file path]:

[code snippet showing the pattern]

Key Points:

• [What to notice]
• [What to replicate]

Requirements

Functional Requirements

1. [Requirement Name]
   • Description: [What it does]
   • Acceptance: [How to verify]

Edge Cases

1. [Edge Case] - [How to handle]

Implementation Notes

DO

• Follow the pattern in [file] for [thing]
• Reuse [utility/component] for [purpose]

DON'T

• Create new [thing] when [existing thing] works
• [Anti-pattern to avoid]

Development Environment

Start Services

[commands to start required services]

Service URLs

Success Criteria

The task is complete when:

1. [Specific, verifiable criterion]
2. [Specific, verifiable criterion]
3. No console errors
4. Existing tests still pass
5. New functionality verified via browser/API

QA Acceptance Criteria

CRITICAL: These criteria must be verified by the QA Agent before sign-off.

Unit Tests

Test	File	What to Verify
[Test Name]	[path]	[What to verify]

Integration Tests

Test	Services	What to Verify
[Test Name]	[service-a ↔ service-b]	[What to verify]

End-to-End Tests

Flow	Steps	Expected Outcome
[Flow Name]	1. [Step] 2. [Step]	[Expected result]

Browser Verification (if frontend)

Page/Component	URL	Checks
[Component]	http://localhost:[port]/[path]	[What to check]

Database Verification (if applicable)

Check	Query/Command	Expected
[Check name]	[command]	[Expected output]

QA Sign-off Requirements

• All unit tests pass
• All integration tests pass
• All E2E tests pass
• Browser verification complete (if applicable)
• Database state verified (if applicable)
• No regressions in existing functionality
• Code follows established patterns
• No security vulnerabilities introduced

SPEC_EOF

---

## CHECKPOINT 2: Validate Spec Document (MANDATORY)

```bash
source auto-build/.venv/bin/activate && python auto-build/validate_spec.py \
    --spec-dir "auto-build/specs/${next_num}-${spec_name}" \
    --checkpoint spec

If validation FAILS:

1. Read the error messages (missing sections, etc.)
2. Edit spec.md to fix issues
3. Re-run validation until it passes

Only proceed after seeing: "PASS"

---

STEP 11: Generate Implementation Plan (Deterministic First)

Try the Python script first (deterministic, reliable):

source auto-build/.venv/bin/activate && python auto-build/planner.py \
    --spec-dir "auto-build/specs/${next_num}-${spec_name}/"

Read the generated plan:

cat "auto-build/specs/${next_num}-${spec_name}/implementation_plan.json"

---

CHECKPOINT 3: Validate Implementation Plan (MANDATORY)

source auto-build/.venv/bin/activate && python auto-build/validate_spec.py \
    --spec-dir "auto-build/specs/${next_num}-${spec_name}" \
    --checkpoint plan

If validation FAILS:

Option A: Auto-fix

source auto-build/.venv/bin/activate && python auto-build/validate_spec.py \
    --spec-dir "auto-build/specs/${next_num}-${spec_name}" \
    --checkpoint plan \
    --auto-fix

Option B: Manual fix

If auto-fix doesn't work, read the errors and fix the JSON:

1. Missing required fields: Add them
2. Invalid status values: Use "pending", "in_progress", "completed", "blocked", "failed"
3. Invalid workflow_type: Use "feature", "refactor", "investigation", "migration", "simple"
4. Missing chunks: Each phase needs at least one chunk with id, description, status

Option C: Regenerate with explicit instructions

If the plan is fundamentally wrong, delete and regenerate:

rm "auto-build/specs/${next_num}-${spec_name}/implementation_plan.json"
source auto-build/.venv/bin/activate && python auto-build/planner.py \
    --spec-dir "auto-build/specs/${next_num}-${spec_name}/"

Re-run validation after each fix attempt. Only proceed after seeing: "PASS"

---

CHECKPOINT 4: Final Validation (MANDATORY)

Run complete validation:

source auto-build/.venv/bin/activate && python auto-build/validate_spec.py \
    --spec-dir "auto-build/specs/${next_num}-${spec_name}" \
    --checkpoint all

ALL checkpoints must PASS before proceeding.

If any fail:

1. Read the specific errors
2. Fix the identified issues
3. Re-run validation
4. Repeat until all pass

---

STEP 12: Confirm and Save

1. Show the user the complete spec.md
2. Show the implementation plan summary
3. Ask: "Does this capture everything? Would you like to modify anything?"
4. Make any requested changes
5. Re-run validation after any changes

---

STEP 13: Analyze Parallelism Opportunities

Look at the generated implementation_plan.json:

Parallelism Rules

Two phases can run in parallel if:

1. They have the same dependencies (identical depends_on arrays)
2. They don't modify the same files (check files_to_modify overlap)
3. They are in different services

Determine Recommended Workers

• 1 worker (default): Sequential phases, any file conflicts, or investigation workflows
• 2 workers: Two independent phases can run at some point
• 3+ workers: Large projects with 3+ services with no file conflicts

---

STEP 14: Provide Next Steps

"Your spec has been saved to auto-build/specs/[number]-[name]/

The folder contains:

• spec.md - Your specification (what to build)
• implementation_plan.json - Chunk-based plan (how to build it)
• project_index.json - Project structure
• context.json - Task-relevant file discovery
• requirements.json - User requirements

All validation checkpoints passed. ✓

Implementation Plan Summary:

• Phases: [N]
• Total Chunks: [N]
• Services: [list]
• Recommended workers: [1|2|3]

To start the autonomous build:

source auto-build/.venv/bin/activate && python auto-build/run.py --spec [number] --parallel [recommended_workers]

The agents will:

1. Work through phases in dependency order
2. Complete one chunk at a time
3. Verify each chunk before moving on
4. QA Agent validates all acceptance criteria before sign-off

QA Validation Loop:

• Run all unit, integration, and E2E tests
• Perform browser verification (if frontend)
• Check database state (if applicable)
• If issues found → Coder Agent fixes → QA re-validates
• Loop continues until all QA criteria pass
• Final sign-off recorded in implementation_plan.json

Press Ctrl+C to pause at any time."

---

Workflow-Specific Guidelines

For FEATURE Workflow

Phases should follow service dependency order:

1. Backend/API first (can be tested with curl)
2. Workers/background jobs second (depend on backend)
3. Frontend last (depends on backend)
4. Integration phase at the end

For REFACTOR Workflow

Phases should follow migration stages:

1. Add new system alongside old (both work)
2. Migrate consumers to new system
3. Remove old system
4. Cleanup and polish

For INVESTIGATION Workflow

Phases should follow debugging process:

1. Reproduce & Instrument
2. Investigate
3. Fix (blocked until phase 2 completes)
4. Verify & Harden

For MIGRATION Workflow

Phases should follow data pipeline:

1. Prepare (write scripts, setup)
2. Test (small batch, verify)
3. Execute (full migration)
4. Cleanup (remove old data)

---

Guidelines for High Success Rate

1. ALWAYS run validation checkpoints - They catch errors before they propagate

2. ALWAYS create requirements.json - The system needs structured requirements

3. ALWAYS scope to specific services - In monorepos, "the whole project" is too vague

4. ALWAYS find reference files - Showing patterns is better than describing them

5. Be specific about files - "Modify src/client/proxy.ts" not "update the proxy code"

6. Fix validation errors immediately - Don't proceed with invalid outputs

7. Keep chunks small - One chunk = one focused change in one service

8. Review the implementation plan - The planner's output should make sense

---

Validation Quick Reference

Checkpoint	Command	When to Run
Prerequisites	--checkpoint prereqs	After creating spec dir
Context	--checkpoint context	After context discovery
Spec Document	--checkpoint spec	After writing spec.md
Implementation Plan	--checkpoint plan	After generating plan
All	--checkpoint all	Before final confirmation

Fix any failures before proceeding to the next step.