solo-sdd

Purpose and mode

Own spec-driven development process for one person or a team, with any coding agent, independent of other spec tools: the algorithm, skills, global agent rules, Claude Code hooks and project templates. The repository is the source of truth; sync.py push puts the files in place. Mode: prod. Prod here is the agent folders on this computer (~/.claude, ~/.codex, ~/.agents, ~/.local/bin): after sync.py push an edit takes effect in all sessions at once.

Sources of truth

• Behaviour contract: solo-sdd/specs/; active work: solo-sdd/changes/; the project intent: solo-sdd/project.md.
• Algorithm: ALGORITHM.md; the lessons the rules grew from: LESSONS.md; the full text of each ## Lessons line is in its section Lessons of this repository under the same id, and a refinement edits both.
• README.md: what lies where and how it is deployed. targets.json: the deployment map.
• Files copied into agent folders are not a source: an edit in place is pulled with sync.py pull.
• solo-sdd/specs/ and the open changes of solo-sdd/changes/ are kept in git. The change archive solo-sdd/changes/archive/ and docs/waiting.md are not in git, they live only in the working folder: the archive is not published.

Working with specs

• One change per session, up to the archive.
• No clarifying questions: a reasoned decision, recorded in the report.
• Work outside the current spec becomes a new change.
• After tasks.md is closed, an independent live test before reporting readiness.

Commands

Project map

Working copy

• Paths: docs/waiting.md, docs/debug-profile.md, docs/rules-audit.md, docs/process-safety-verification.md, global/claude-gui.py, global/claude-process-safety-settings.json, global/claude-safe.py, tests/eval/sets/, tests/probe_claude_development.py, tests/probe_claude_process_safety.py, tests/test_claude_gui.py, tests/test_claude_safe.py

Boundaries and invariants

• Edits only here, then sync.py push. Files in agent folders are not edited by hand.
• sync.py push does not overwrite a copy edited in place (drift); before overwriting it saves the previous text to ~/.local/share/solo-sdd/backup/.
• Hooks are fail-open: an internal error lets the action through and is written to ~/.claude/hook-state/errors.log.
• All repository text is in English, with no Cyrillic letter (tests/test_repo_language.py).

Checks

Before "done": the Tests row, the lint from the table without output, python3 -m solo_sdd validate --all, python3 sync.py status without unexpected drift, the change's live scenario.

Delivery

• Mode: pr
• Merge: squash
• PR title: the change name
• Deploy: no; deployment to agent folders is done separately (sync.py push).
• CI: an agent merges a PR through sdd-pr.py merge only when sdd-pr.py wait <url> gives CI: green. On CI: red, CI: infra or CI: codeql the agent fixes, reruns and waits again as /ship (under the dispatcher, spec-dispatch) says; a PR that is still not green waits for the owner: an agent never merges around a red or missing check (docs/release.md).

Security

• Paid model calls in tests: only the cheapest (global/model-policy.json).
• sync.py push changes the agents' working folders on this computer: this is a prod action, check sync.py status after it.
• There are no secrets in the repository and there must be none.

Lessons

• A stand runs exactly what it means to test: real inputs through the host, a base commit pinned by hash and read apart from the working folder, reads on a condition, every imported module copied. (full text)
• Environment detection looks only inside the passed home and PATH, and a test fixture pins every git and interpreter default it relies on. (full text)
• A claim about a tool's behaviour, a record of edited files or of affected tests is written only after checking it here against the tool or the source. (full text)
• An unnamed "our product" means solo-sdd itself; the owner's other products are neither the subject nor a source of facts unless named. (full text)
• A reader of a format reads it by that program's own rules, refuses broken input before its first side effect, and never skips a line or entry silently. (full text)
• A session capability the agents depend on is probed once before launch; its absence stops the launch only when the project declares the need. (full text)
• A check of printed output or a document matches by prefix and by whole item with whitespace collapsed, never by position or physical line. (full text)
• A stand that grades a judgement call expects one answer only where every correct reading gives it. (full text)
• A deployment gate is worded for the whole repository, a publication target handed to a new name is guarded in every clone, and a deploying command is never run to learn its options. (full text)
• A cleanup removes only what the current map and its own sources name, keeps and names everything else, and takes a source as gone only when it is missing. (full text)
• A value that falls back to a default is reported with its source, every reader takes a setting from one shared definition, and an inferred choice is stored once made. (full text)
• A bulk wording replacement keeps quoted program output verbatim and is reread line by line. (full text)
• A script that moves or rewrites a branch decides from the commits themselves, never from a setting. (full text)
• An input check covers the edge forms of its input (digits, a closed stdin, line endings, links, escaping, non-blocking reads) at one point every reader passes. (full text)
• Before a test of a removed requirement is deleted, its checks for kept requirements move into a kept test. (full text)
• A new outcome, exemption or ban of a step is written where the rule it changes is read, and checked against every rule that requires what it bans. (full text)
• A scenario of a new behaviour names what only the new code produces, and a plan for a feature covers its life around the request. (full text)
• A gate a person's marks open takes the confirmation from a record the agent cannot produce, and evidence the agent writes is matched against a source written before the work. (full text)
• A guard that exempts part of a shell command reads it by the shell's and each program's grammar, refuses what it cannot read, and is replayed against the forms decided before. (full text)
• A path that becomes git-ignored is checked through every merge, reset, abort and mirror step for a deletion of its copy, and a temporary index copy keeps the index's time. (full text)