/initspec Command

Initialize the Apex Spec System in the current project directory.

Role & Mindset

You are a senior engineer who is obsessive about pristine code — zero errors, zero warnings, zero lint issues. You are known for clean project scaffolding, rigorous structure discipline, and treating implementation as a craft: methodical, patient, and uncompromising on quality.

Your Task

Set up the complete spec system directory structure and initial files for a new or existing project. All spec system files are stored in the .spec_system/ directory to keep the project root clean.

Steps

1. Check Current State

First, check if the spec system is already initialized:

• Look for .spec_system/state.json
• Check for .spec_system/PRD/ directory
• Check for .spec_system/specs/ directory

If already initialized, ask the user if they want to reinitialize (this will reset state).

2. Gather Project Information

Ask the user for:

• Project name: Name of the project
• Project description: Brief description of what the project does
• First phase name: Name for Phase 00 (default: "Foundation")

3. Create Directory Structure

Create the following directories:

mkdir -p .spec_system/PRD/phase_00
mkdir -p .spec_system/specs
mkdir -p .spec_system/audit
mkdir -p .spec_system/archive/backups
mkdir -p .spec_system/archive/sessions
mkdir -p .spec_system/archive/planning
mkdir -p .spec_system/archive/PRD
mkdir -p .spec_system/archive/phases

4. Create state.json

Create .spec_system/state.json:

{
  "version": "2.0",
  "project_name": "[PROJECT_NAME]",
  "description": "[PROJECT_DESCRIPTION]",
  "current_phase": 0,
  "current_session": null,
  "phases": {
    "0": {
      "name": "[PHASE_NAME]",
      "status": "not_started",
      "session_count": 0
    }
  },
  "completed_sessions": [],
  "next_session_history": []
}

5. Create PRD Template

Create .spec_system/PRD/PRD.md with a starter template:

# [PROJECT_NAME] - Product Requirements Document

## Overview

[PROJECT_DESCRIPTION]

## Goals

1. [Goal 1]
2. [Goal 2]
3. [Goal 3]

## Phases

| Phase | Name | Sessions | Status |
|-------|------|----------|--------|
| 00 | [PHASE_NAME] | TBD | Not Started |

## Phase 00: [PHASE_NAME]

### Objectives

1. [Objective 1]
2. [Objective 2]

### Sessions (To Be Defined)

Use `/nextsession` to get recommendations for sessions to implement.

## Technical Stack

- [Technology 1]
- [Technology 2]

## Success Criteria

- [ ] [Criterion 1]
- [ ] [Criterion 2]

6. Create CONSIDERATIONS.md

Create .spec_system/CONSIDERATIONS.md (institutional memory for AI assistants):

# Considerations

> Institutional memory for AI assistants. Updated between phases via /carryforward.
> **Line budget**: 600 max | **Last updated**: Phase 00 (YYYY-MM-DD)

---

## Active Concerns

Items requiring attention in upcoming phases. Review before each session.

### Technical Debt
<!-- Max 5 items -->

*None yet - add items as technical debt accumulates.*

### External Dependencies
<!-- Max 5 items -->

*None yet - add items when external API/service risks are identified.*

### Performance / Security
<!-- Max 5 items -->

*None yet - add items when thresholds or security requirements emerge.*

### Architecture
<!-- Max 5 items -->

*None yet - add items when architectural constraints are discovered.*

---

## Lessons Learned

Proven patterns and anti-patterns. Reference during implementation.

### What Worked
<!-- Max 15 items -->

*None yet - add patterns that prove effective.*

### What to Avoid
<!-- Max 10 items -->

*None yet - add anti-patterns discovered during implementation.*

### Tool/Library Notes
<!-- Max 5 items -->

*None yet - add key insights about tools and libraries.*

---

## Resolved

Recently closed items (buffer - rotates out after 2 phases).

| Phase | Item | Resolution |
|-------|------|------------|
| - | *No resolved items yet* | - |

---

*Auto-generated by /initspec. Updated by /carryforward between phases.*

7. Create CONVENTIONS.md

Create .spec_system/CONVENTIONS.md (coding standards and team conventions):

# CONVENTIONS.md

## Guiding Principles

- Optimize for readability over cleverness
- Code is written once, read many times
- Consistency beats personal preference
- If it can be automated, automate it
- When writing code: Make NO assumptions. Do not be lazy.  Pattern match precisely.  Do not skim when you need detailed info from documents. Validate systematically.

## Naming

- Be descriptive over concise: `getUserById` > `getUser` > `fetch`
- Booleans read as questions: `isActive`, `hasPermission`, `shouldRetry`
- Functions describe actions: `calculateTotal`, `validateInput`, `sendNotification`
- Avoid abbreviations unless universally understood (`id`, `url`, `config` are fine)
- Match domain language--use the same terms as product/design/stakeholders

## Files & Structure

- One concept per file where practical
- File names reflect their primary export or purpose
- Group by feature/domain, not by type (prefer `/orders/api.ts` over `/api/orders.ts`)
- Keep nesting shallow--if you're 4+ levels deep, reconsider

## Functions & Modules

- Functions do one thing
- If a function needs a comment explaining what it does, consider renaming it
- Keep functions short enough to read without scrolling
- Avoid side effects where possible; be explicit when they exist

## Comments

- Explain *why*, not *what*
- Delete commented-out code--that's what git is for
- TODOs include context: `// TODO(name): reason, ticket if applicable`
- Update or remove comments when code changes

## Error Handling

- Fail fast and loud in development
- Fail gracefully in production
- Errors should be actionable--include context for debugging
- Don't swallow errors silently

## Testing

- Test behavior, not implementation
- A test's name should describe the scenario and expectation
- If it's hard to test, the design might need rethinking
- Flaky tests get fixed or deleted--never ignored

## Git & Version Control

- Commit messages: imperative mood, concise (`Add user validation` not `Added some validation stuff`)
- One logical change per commit
- Branch names: `type/short-description` (e.g., `feat/user-auth`, `fix/cart-total`)
- Keep commits atomic enough to revert safely

## Pull Requests

- Small PRs get better reviews
- Description explains the *what* and *why*--reviewers can see the *how*
- Link relevant tickets/context
- Review your own PR before requesting others

## Code Review

- Critique code, not people
- Ask questions rather than make demands
- Approve when it's good enough, not perfect
- Nitpicks are labeled as such

## Dependencies

- Fewer dependencies = less risk
- Justify additions; prefer well-maintained, focused libraries
- Pin versions; update intentionally

## Local Dev Tools

| Category | Tool | Config |
|----------|------|--------|
| Formatter | not configured | - |
| Linter | not configured | - |
| Type Safety | not configured | - |
| Testing | not configured | - |
| Observability | not configured | - |
| Git Hooks | not configured | - |

## When In Doubt

- Ask
- Leave it better than you found it
- Ship, learn, iterate

8. Create Phase PRD

Create .spec_system/PRD/phase_00/PRD_phase_00.md:

# Phase 00: [PHASE_NAME]

**Status**: Not Started
**Progress**: 0/0 sessions (0%)

## Overview

[Phase description - to be filled in]

## Progress Tracker

| Session | Name | Status | Validated |
|---------|------|--------|-----------|
| - | No sessions defined | - | - |

## Next Steps

Run `/nextsession` to get the first session recommendation.

9. Copy Scripts Locally (Optional)

Scripts can run from either location:

• Plugin (default): ${CLAUDE_PLUGIN_ROOT}/scripts/ - Always up-to-date with plugin updates
• Local: .spec_system/scripts/ - Allows per-project customization, isolated from plugin updates

If local scripts exist, commands will use them automatically (local takes precedence).

Ask user: "Do you want to copy scripts locally for customization, or use them from the plugin (recommended)?"

If the user wants local scripts:

mkdir -p .spec_system/scripts
cp ${CLAUDE_PLUGIN_ROOT}/scripts/*.sh .spec_system/scripts/
chmod +x .spec_system/scripts/*.sh

Note: Local scripts won't receive plugin updates automatically. To update, delete .spec_system/scripts/ and re-copy, or just remove it to fall back to plugin scripts.

10. Report Success

Tell the user:

Apex Spec System initialized!

Created:
- .spec_system/state.json (project state tracking)
- .spec_system/PRD/PRD.md (product requirements document)
- .spec_system/PRD/phase_00/PRD_phase_00.md (phase tracker)
- .spec_system/CONSIDERATIONS.md (institutional memory for AI)
- .spec_system/CONVENTIONS.md (coding standards and team conventions)
- .spec_system/specs/ (session specifications directory)
- .spec_system/audit/ (audit reports directory)
- .spec_system/archive/ (completed work archive)

Next Steps:
1. Edit .spec_system/PRD/PRD.md with your project requirements
2. Customize .spec_system/CONVENTIONS.md with your project's coding standards (optional but recommended)
3. Run /phasebuild to define sessions for Phase 00 (recommended for new projects)
   OR run /nextsession directly if you already know your first session
4. Follow the workflow: /nextsession -> /sessionspec -> /tasks -> /implement -> /validate -> /updateprd
5. Repeat step 4 until all sessions in the phase are complete
6. Run /carryforward (optional) to capture lessons learned, then /phasebuild for next phase

Rules

1. Never overwrite existing .spec_system/state.json without user confirmation
2. Use ASCII-only characters in all generated files
3. Unix LF line endings only
4. Create minimal structure - don't over-engineer initial setup

Output

After initialization, show the created structure and guide the user to their next step.