autospec

# 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

```bash
# 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

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

### First-Time Project Setup

```bash
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`:

1. **Validation-First**: All workflow transitions validated before proceeding
2. **Test-First Development** (NON-NEGOTIABLE): Tests written before implementation
3. **Performance Standards**: Validation functions <10ms
4. **Idempotency**: All operations idempotent; configurable retry limits
5. **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:
1. `internal/config/schema.go` - Add to `KnownKeys` map
2. `internal/config/defaults.go` - Add to YAML template AND `GetDefaults()` function
3. `internal/config/validate.go` - Add validation if needed

## Coding Standards

### Error Handling (CRITICAL)

**Always wrap errors with context** - never bare `return err`:
```go
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:

```go
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:

1. **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.

2. **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.

## Branches, Releases & Dependency PRs

- `dev` (GitLab `origin` only) is the integration branch; never push `dev` to GitHub (`gh`).
- `main` is frozen on both providers and must stay free of `video/` history (enforced by `go run ./cmd/mainboundary`). Never merge `dev` into `main`; cherry-pick onto a branch from `gh/main`.
- Releases, README/docs/dependency syncs to `main`, freeze/unfreeze, and Dependabot PR triage follow the private `release` skill (`.agents/skills/release/SKILL.md`). Ariel syncs `main` manually: never start, propose, or schedule a `main` sync, release, or CI repair unless Ariel explicitly asks. Land work on `dev` only.
- Save CI minutes: when asked to sync, batch all commits onto the PR branch before the first push (every push runs the full GitHub CI), and skip GitLab MRs for syncs.
- Dependabot PRs: never merge in the GitHub UI. When asked, close them if `main` already has the version; otherwise cherry-pick to `dev` and leave the `main` sync to Ariel.
- `make test` skips E2E and integration suites. Before any `main` update, also run `go test -tags=e2e ./tests/e2e/...` and `go test -tags=integration ./tests/integration/...` with agent CLIs removed from PATH, as CI does.

## Git Commits in Sandbox Mode

```bash
# 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

```bash
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)