CLAUDE.md

Guidance for Claude Code when working with this repository.

Autospec Claude Skills

autospec init --ai claude installs Claude project skills in .claude/skills/autospec.*/SKILL.md. They preserve existing slash-style invocation such as /autospec.plan and set disable-model-invocation: true so agents do not invoke them automatically.

Prerequisites

Go 1.25+: Check with go version
Claude CLI: Authenticated (claude --version)
Make, golangci-lint: For build/lint (make lint)

Commands

# Build & Dev
make build          # Build for current platform
make test           # Run all tests (quiet, shows failures only)
make test-v         # Run all tests (verbose, for debugging)
make fmt            # Format Go code (run before committing)
make lint           # Run all linters

# Single test
go test -run TestName ./internal/package/

# CLI usage (run `autospec --help` for full reference)
autospec run -a "feature description"    # All stages: specify → plan → tasks → implement
autospec prep "feature description"      # Planning only: specify → plan → tasks
autospec implement --phases              # Each phase in separate session
autospec implement --tasks               # Each task in separate session
autospec st                              # Show status and task progress
autospec doctor                          # Check dependencies

Post-Change Polish (REQUIRED)

After significant code changes, automatically invoke the repo-local polish skill before final handoff. Use it to update changelog/docs and run the required validation targets. Do not wait for an explicit /polish request unless the change is trivial or docs-only.

Core Workflow

Stage Dependencies (MUST follow this order)

constitution → specify → plan → tasks → implement
     ↓            ↓        ↓       ↓
constitution.yaml spec.yaml plan.yaml tasks.yaml

Stage	Requires	Produces
`constitution`	—	`.autospec/constitution.yaml`
`specify`	constitution	`specs/NNN-feature/spec.yaml`
`plan`	spec.yaml	`plan.yaml`
`tasks`	plan.yaml	`tasks.yaml`
`implement`	tasks.yaml	code changes

Constitution is REQUIRED before any workflow stage.

What `autospec init` Does

Creates config (~/.config/autospec/config.yml or .autospec/config.yml)
Installs agent-native prompts (Claude skills in .claude/skills/, shared Codex/OpenCode skills in .agents/skills/)
Configures agent permissions and sandbox settings
Prompts for constitution creation (one-time per project)

First-Time Project Setup

autospec init              # Interactive setup (config + agent + constitution)
autospec doctor            # Verify dependencies
autospec prep "feature"    # specify → plan → tasks
autospec implement         # Execute tasks

Documentation

Review relevant docs before implementation:

File	Purpose
`docs/internal/architecture.md`	System design, component diagrams, execution flows
`docs/internal/go-best-practices.md`	Go conventions, naming, error handling patterns
`docs/public/reference.md`	Complete CLI command reference with all flags
`docs/internal/internals.md`	Spec detection, validation, retry system, phase context
`docs/public/TIMEOUT.md`	Timeout configuration and behavior
`docs/internal/YAML-STRUCTURED-OUTPUT.md`	YAML artifact schemas and slash commands
`docs/public/checklists.md`	Checklist generation, validation, and implementation gating
`docs/internal/risks.md`	Risk documentation in plan.yaml
`docs/public/SHELL-COMPLETION.md`	Shell completion implementation
`docs/public/troubleshooting.md`	Common issues and solutions
`docs/public/claude-settings.md`	Claude Code settings and sandboxing configuration
`docs/public/opencode-settings.md`	OpenCode configuration, permissions, and command patterns
`docs/public/agents.md`	CLI agent configuration (Claude and OpenCode supported)

Architecture Overview

autospec is a Go CLI that orchestrates SpecKit workflows. Key distinction:

Stage: High-level workflow step (specify, plan, tasks, implement)
Phase: Task grouping within implementation (Phase 1: Setup, Phase 2: Core, etc.)

Package Structure

cmd/autospec/main.go: Entry point
internal/cli/: Cobra commands (root + orchestration)
- internal/cli/stages/: Stage commands (specify, plan, tasks, implement)
- internal/cli/config/: Configuration commands (init, config, migrate, doctor)
- internal/cli/util/: Utility commands (status, history, version, clean, view)
- internal/cli/admin/: Admin commands (commands, completion, uninstall)
- internal/cli/worktree/: Worktree management commands (create, list, remove, prune)
- internal/cli/shared/: Shared types and constants
internal/workflow/: Workflow orchestration and agent execution
internal/config/: Hierarchical config (env > project > user > defaults)
internal/validation/: Artifact validation (<10ms performance contract)
internal/retry/: Persistent retry state
internal/spec/: Spec detection from git branch or recent directory
internal/agent/: Agent abstraction (Claude, Gemini, Cline, etc.)
internal/cliagent/: CLI agent integration and Configurator interface
internal/worktree/: Git worktree management logic

Configuration

Priority: Environment (AUTOSPEC_*) > .autospec/config.yml > ~/.config/autospec/config.yml > defaults

Key settings: agent_preset, max_retries, specs_dir, timeout, implement_method

Note: The legacy claude_cmd and claude_args fields are deprecated. Use agent_preset instead. See docs/public/agents.md.

Constitution Principles

From .autospec/constitution.yaml:

Validation-First: All workflow transitions validated before proceeding
Test-First Development (NON-NEGOTIABLE): Tests written before implementation
Performance Standards: Validation functions <10ms
Idempotency: All operations idempotent; configurable retry limits
Command Template Independence (NON-NEGOTIABLE): internal/commands/*.md must be project-agnostic—no MCP tools, no Claude Code tools, no autospec-internal paths

Config Changes (REQUIRED)

When adding, changing, or removing config fields, update ALL locations:

internal/config/schema.go - Add to KnownKeys map
internal/config/defaults.go - Add to YAML template AND GetDefaults() function
internal/config/validate.go - Add validation if needed

Coding Standards

Error Handling (CRITICAL)

Always wrap errors with context - never bare return err:

return fmt.Errorf("loading config: %w", err)  // GOOD

Exceptions: Pass-through helpers, test code.

Function Length

Keep functions under 40 lines. Extract helpers for pre-validation, core logic, post-processing, and output formatting.

Map-Based Table Tests (REQUIRED)

Use tests := map[string]struct{...} with for name, tt := range tests { t.Run(name, ...) }.

CLI Command Lifecycle Wrapper (REQUIRED)

Workflow commands MUST use lifecycle.RunWithHistory() for notifications, timing, and history:

notifHandler := notify.NewHandler(cfg.Notifications)
historyLogger := history.NewWriter(cfg.StateDir, cfg.MaxHistoryEntries)
return lifecycle.RunWithHistory(notifHandler, historyLogger, "cmd-name", specName, func() error {
    return orch.ExecuteXxx(...)
})

For context-aware commands: lifecycle.RunWithHistoryContext(cmd.Context(), ...).

Required for: specify, plan, tasks, clarify, analyze, checklist, constitution, prep, run, implement, all.

Regression test: TestAllCommandsHaveNotificationSupport in internal/cli/specify_test.go.

Spec Generation (MUST)

When generating spec.yaml, ALWAYS include these as NFRs (category: code_quality):

Functions under 40 lines
Errors wrapped with context (fmt.Errorf("doing X: %w", err))
Map-based table tests (map[string]struct)
Accept interfaces, return concrete types

Final FR MUST require: make test && make fmt && make lint && make build all exit 0.

Task Generation (MUST)

When generating tasks.yaml, the final tasks MUST include:

Manual testing plan: Create .dev/tasks/<spec-name>.md with a plan for manually testing all changes. Include a "Report Summaries" section to be filled in once manual testing is complete. Do NOT execute the tests—just map out core manual testing steps for that spec.
Changelog update: Add 1-3 user-facing bullets to internal/changelog/changelog.yaml, then run make changelog-sync to regenerate CHANGELOG.md.

This ensures all features have documented test plans and are visible to users.

Changelog Workflow (YAML-First)

Edit internal/changelog/changelog.yaml directly, then run make changelog-sync to regenerate CHANGELOG.md. Never edit CHANGELOG.md directly—it is auto-generated from the YAML source.

Public changelog entries must describe user-visible behavior: CLI changes, config changes, compatibility changes, docs users rely on, security fixes, or bug fixes users can observe. Maintainer-only process, governance, prompt hygiene, test strategy, architecture-boundary, or release-workflow notes belong under the version's internal: tier in internal/changelog/changelog.yaml, not in public added/changed/fixed release notes.

Git Commits in Sandbox Mode

# BAD - heredocs fail in sandbox mode
git commit -m "$(cat <<'EOF'
commit message
EOF
)"

# GOOD - use regular quoted string with newlines
git commit -m "feat(scope): description

Body text here.
"

Pre-Commit Checklist

make fmt && make lint && make test && make build

All must pass before committing. Run make test-v for verbose output on failures.

Common Gotchas

Branch naming: Must match ^\d{3}-.+$ (e.g., 001-feature) for spec auto-detection
Slash commands vs skills: Claude Code may incorrectly invoke slash commands as skills (see docs/public/troubleshooting.md)
Sandbox heredocs: Use quoted strings, not heredocs, for git commits in sandbox mode
Constitution required: All workflow stages fail without .autospec/constitution.yaml

Key Files

~/.config/autospec/config.yml: User config
.autospec/config.yml: Project config
.autospec/constitution.yaml: Project principles (REQUIRED)
~/.autospec/state/retry.json: Retry state
specs/*/: Feature specs (spec.yaml, plan.yaml, tasks.yaml)

FilesExpand file tree

CLAUDE.md

Latest commit

History

CLAUDE.md

File metadata and controls

CLAUDE.md

Autospec Claude Skills

Prerequisites

Commands

Post-Change Polish (REQUIRED)

Core Workflow

Stage Dependencies (MUST follow this order)

What autospec init Does

First-Time Project Setup

Documentation

Architecture Overview

Package Structure

Configuration

Constitution Principles

Config Changes (REQUIRED)

Coding Standards

Error Handling (CRITICAL)

Function Length

Map-Based Table Tests (REQUIRED)

CLI Command Lifecycle Wrapper (REQUIRED)

Spec Generation (MUST)

Task Generation (MUST)

Changelog Workflow (YAML-First)

Git Commits in Sandbox Mode

Pre-Commit Checklist

Common Gotchas

Key Files

What `autospec init` Does