# SpecSoloist — Task Backlog

> **For new Claude sessions:** Read this first. It orients you on project state and points
> you to the right task. Then read `AGENTS.md` for full project context.
> Completed tasks are in `tasks/HISTORY.md`.

---

## What Is SpecSoloist?

A spec-driven AI coding framework. Developers write `.spec.md` files describing *what* code
should do; the `sp conduct` command spawns AI agents that write the implementation and tests.

The broader goal right now: **make SpecSoloist ready for developing and maintaining FastHTML
and Next.js web applications.**

---

## Current State

| Layer | Status |
|-------|--------|
| Core framework | Stable — parser, compiler, runner, resolver, manifest |
| Agent-first CLI | Done — `sp conduct`, `sp compose`, `sp respec`, `sp fix`, `sp vibe`, `sp diff` |
| Quine (self-hosting) | Validated — `sp conduct score/` regenerates `src/` with 320 tests passing (2026-03-19); weekly CI in `.github/workflows/quine.yaml` |
| FastHTML example | Validated — 23 tests passing (`examples/fasthtml_app/`) |
| Next.js example | Validated — 22 tests passing (`examples/nextjs_ai_chat/`) |
| Documentation | Solid — mkdocstrings + Google docstrings live; spec-types.md + example docs complete (HK-11 done) |

Key commands:
```bash
uv run python -m pytest tests/   # 355 tests — must stay green
uv run ruff check src/           # must pass with 0 errors
sp conduct score/ --model haiku --auto-accept   # quine attempt
```

---

## Task Status

### 🔲 Housekeeping

_No open housekeeping tasks._

### 🔲 User Actions

| # | Action | Summary |
|---|--------|---------|
| **UA-01** | Add `ANTHROPIC_API_KEY` to GitHub repo secrets | Required for quine CI (`.github/workflows/quine.yaml`) to run. Settings → Secrets → Actions → New secret. |

### 🔲 To Do — in priority order

_No open tasks._

---

## How to Pick Up a Task

1. **Read this file** (done ✓)
2. **Read `AGENTS.md`** — project structure, key commands, current phase
3. **Pick the lowest-numbered uncompleted task** (or one the user specifies)
4. **Read the task file** in full — context, steps, files to read, success criteria
5. **Read all source files listed in the task** before writing any code or forming an approach.
   Task files intentionally leave some implementation decisions open; the right answer usually
   emerges from reading the code. Decide, then proceed — don't ask about decisions the source
   files resolve.
6. **Verify** with `uv run python -m pytest tests/` and `uv run ruff check src/` before committing

When done with a task, move it to `tasks/HISTORY.md` and commit.

---

## Working Principles

These apply to every task. Knowing them upfront prevents the most common mistakes:

**Minimal footprint.** Extend existing call sites rather than restructuring them. If `compile_code()`
needs a new parameter, add it with a default of `None` so all existing callers still work.

**Display logic lives in `cli.py`.** The validator, parser, and compiler return data. `cli.py`
formats it for humans. Don't embed display strings in lower layers.

**Unit tests for framework changes; end-to-end as a smoke test.** When a task changes parser,
compiler, or runner behaviour, write unit tests for those layers directly. End-to-end via
`sp conduct` is a sanity check, not the primary verification.

**Reference specs have three sections** — `# Overview` (required), `# API` (required),
`# Verification` (recommended — warn if absent). The `# Verification` section contains
3–10 lines of import and smoke-test snippets compiled into `tests/test_{name}.py`. This makes
reference specs *verified documentation* that fails CI when the library API drifts.

**No generated files committed.** `src/` and `tests/` in examples are gitignored. Only specs,
arrangements, READMEs, and framework source committed.

**`sp conduct` nested session.** Running `sp conduct` inside Claude Code blocks subprocess
spawning. Run from a terminal outside Claude Code, or use `--no-agent`. Alternatively, use
the `Agent` tool with `subagent_type="conductor"` from within a Claude Code session.

**Subprocess `cwd=` must use `Path(__file__).parent.parent`.** Never pass a literal string
like `cwd="."` — it breaks when tests are run from any directory other than the repo root.
Use `Path(__file__).parent.parent` to resolve the repo root relative to the test file, or
define a module-level `REPO_ROOT = Path(__file__).parent.parent` constant and reference it.

---

## Key Architectural Decisions (already made)

- **`type: reference`** — use for any spec documenting a third-party library. No implementation
  generated. Spec body injected into prompts of dependent soloists via `reference_specs: dict[str, ParsedSpec]`
  passed through `compile_code()`. Verification snippets compiled to a test file.

- **Multi-spec web apps** — separate layout, routing, and state into distinct specs. One
  combined spec can't express UI completeness. See `tasks/HISTORY.md` task 06 for the pattern.

- **Arrangements are build config** — language, output paths, tool versions, env var names.
  Specs are language-agnostic. Never put language-specific details in specs.
