solo-sdd 0.2.0__py3-none-any.whl

solo_sdd/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

solo_sdd/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from solo_sdd.cli import main
+
+sys.exit(main())

solo_sdd/cli.py

@@ -0,0 +1,204 @@
+"""solo-sdd entry point: command parsing."""
+import difflib, os, sys
+
+from solo_sdd import __version__, doctor, hooks, import_openspec, integration_run, integrations, keywords, layout, process_cli, process_format, providers, settings
+from solo_sdd import init as project_init
+
+layout.PULL_HINT = "solo-sdd sync pull"
+
+COMMANDS = """solo-sdd commands:
+  --version                          version
+  status                             state of every copy
+  install [--agents a,b] [--hooks] [--global-rules] [--replace-foreign]
+                                     lay out skills, scripts and templates for the agents (default: the last choice, else
+                                     the detected ones; other always); --hooks connects the hooks in settings.json;
+                                     --global-rules also writes the rules block into ~/AGENTS.md, ~/.codex/AGENTS.md and
+                                     ~/.claude/CLAUDE.md (a home that has the block from an earlier version keeps it);
+                                     a file solo-sdd did not lay out is kept, --replace-foreign replaces it with a backup
+  uninstall [--purge | --global-rules]
+                                     remove copies and hooks; --purge also removes solo-sdd data and a solo schema left by an
+                                     old version; --global-rules removes only the global rules block
+  init [folder] [--yes] [--solo|--team] [--agents a,b] [--delivery local|pr] [--set key=value]... [--reconfigure]
+                                     prepare a project git repository: solo-sdd/ (project.md, analyze.md, specs/, changes/,
+                                     config from the detected authors, CODEOWNERS, branch protection, remote and agents;
+                                     asks on a terminal), docs/waiting.md, the rules block in AGENTS.md and CLAUDE.md
+                                     (rules.scope: global writes none); --reconfigure asks again for every setting
+  doctor                             check the environment: python, copies, hooks, agents and their gaps, gh, AGENTS.md keywords
+  update [--replace-foreign]         repeat the layout, suggest a package upgrade
+  sync pull <name> [--from <place>]  take an edit made in place back into the repository
+  migrate-agents [folder] [--write]  rename pre-English AGENTS.md headings and items to English; without --write only the diff
+  validate [<id>] [--all] [--json]   check the solo-sdd/ process tree (one change or all), no external program
+  list [--specs] [--json]            open changes with task progress and CLAIM/WAITING, or main specs with requirement counts
+  new <id>                           create solo-sdd/changes/<id>/ from the templates
+  archive <id> [--yes] [--force]     apply the change's deltas to the main specs and move it to changes/archive/
+  config list|get <key>|set <key> <value>|unset <key>
+                                     project settings in solo-sdd/config: every key with its value and source, one value, change one line
+  integrations list|enable <name>|disable <name>
+                                     integrations of solo-sdd/integrations/, ~/.local/share/solo-sdd/integrations/ and
+                                     the bundled ones with their source and state; enable or disable one by the integrations
+                                     line of solo-sdd/config (integrations.off for a bundled one, enabled unless it names it)
+                                     and rewrite the AGENTS.md block with the rules.md of the enabled ones
+  check --point checks|ship [--changed] [--change <id>]
+                                     run the enabled integrations of the point (--changed: those whose applies matches a
+                                     changed file), one PASS|FAIL|SKIP line each; the result is recorded by the working
+                                     tree under ~/.local/share/solo-sdd/checks/ and reused on the same tree; --change
+                                     puts one Integrations line of the point into the change's verification.md Result
+  check --point review|audit [--changed] [--tag <tag>]
+                                     run nothing: one MATERIAL <name>: <path> line per enabled integration of the point;
+                                     --tag: per enabled one with the tag, the bundled ones included, also outside a project
+  import openspec [folder] [--write] plan of converting openspec/ into solo-sdd/; --write creates solo-sdd/, openspec/ stays"""
+
+
+def upgrade_hint(prefix, root):
+    if "/uv/tools/" in prefix:
+        return "uv tool upgrade solo-sdd"
+    if "/pipx/venvs/" in prefix:
+        return "pipx upgrade solo-sdd"
+    if "node_modules" in root:
+        return "npm update -g solo-sdd"
+    if os.path.exists(os.path.join(root, ".git")):
+        return f"git pull in {root}"
+    return "python3 -m pip install --upgrade solo-sdd"
+
+
+def install(with_hooks=False, agents=None, rules=False, replace_foreign=False):
+    if agents is not None:
+        try:
+            agents = providers.parse(agents)
+        except ValueError as e:
+            print(e)
+            return 1
+    state = layout.load_state()
+    if "claude" not in (agents or layout.chosen(state)) and (with_hooks or state.get("_hooks")):
+        print("hooks need claude among the agents: solo-sdd install --agents claude,... --hooks"
+              + ("; the connected hooks go with solo-sdd uninstall" if state.get("_hooks") else ""))
+        return 1
+    problems = layout.push(agents=agents, rules=rules, replace_foreign=replace_foreign)
+    for name in agents or layout.chosen(layout.load_state()):
+        if not providers.probed(name):
+            print("%s: %s" % (name, providers.unprobed()))
+    connected = hooks.setup() if with_hooks else 0
+    return 1 if problems or connected else 0
+
+
+def uninstall(purge=False):
+    layout.load_targets()  # a bad map stops before the hooks are restored, not halfway
+    steps = layout.load_state().get("_hooks")
+    code = hooks.restore(steps) if steps else 0
+    if code == 0:
+        state = layout.load_state()
+        if state.pop("_hooks", None) is not None:
+            layout.save_state(state)
+    return 1 if layout.uninstall(purge) or code else 0
+
+
+def update(replace_foreign=False):
+    problems = layout.push(replace_foreign=replace_foreign)
+    print(upgrade_hint(sys.prefix, layout.REPO))
+    return 1 if problems else 0
+
+
+def status():
+    state = layout.load_state()
+    print(f"source: {state.get('_source', layout.REPO)} {state.get('_version', __version__)}")
+    layout.status()
+    return 0
+
+
+def migrate_agents(folder=".", write=False):
+    """Diff of AGENTS.md with the pre-English headings and items renamed; --write applies it."""
+    path = os.path.join(folder, "AGENTS.md")
+    try:
+        with open(path, encoding="utf-8", newline="") as f:
+            old = f.read()
+    except OSError as e:
+        print(f"no AGENTS.md: {path}: {e.strerror}")
+        return 1
+    new, found = keywords.migrate_agents(old)
+    if new == old:
+        print(f"{path}: nothing to change")
+        return 0
+    sys.stdout.writelines(difflib.unified_diff(old.splitlines(True), new.splitlines(True), "a/AGENTS.md", "b/AGENTS.md"))
+    if write:
+        with open(path, "w", encoding="utf-8", newline="") as f:
+            f.write(new)
+        print(f"{path}: rewritten ({', '.join(found)})")
+    else:
+        print(f"{path}: not changed; apply with: solo-sdd migrate-agents {folder} --write")
+    return 0
+
+
+def main(argv=None):
+    try:
+        return _main(argv)
+    except layout.BrokenState as e:
+        print(f"fail state: {e}")
+        return 1
+    except layout.BadTargets as e:
+        print(f"fail {e}")
+        return 1
+
+
+def _main(argv=None):
+    argv = sys.argv[1:] if argv is None else list(argv)
+    if argv == ["--version"]:
+        print(__version__)
+        return 0
+    if argv in (["status"], ["update"], ["doctor"]):
+        return {"status": status, "update": update, "doctor": doctor.run}[argv[0]]()
+    if argv == ["update", "--replace-foreign"]:
+        return update(replace_foreign=True)
+    if argv and argv[0] == "init":
+        code = project_init.main(argv[1:])
+        if code is not None:
+            return code
+    if argv and argv[0] == "install":
+        flags = [a for a in argv[1:] if a in ("--hooks", "--global-rules", "--replace-foreign")]
+        rest = [a for a in argv[1:] if a not in flags]
+        if len(set(flags)) == len(flags) and (rest == [] or (len(rest) == 2 and rest[0] == "--agents")):
+            return install("--hooks" in flags, rest[1] if rest else None, "--global-rules" in flags,
+                           "--replace-foreign" in flags)
+    if argv and argv[0] == "uninstall" and argv[1:] in ([], ["--purge"]):
+        return uninstall(bool(argv[1:]))
+    if argv == ["uninstall", "--global-rules"]:
+        return layout.uninstall_rules()
+    if argv and argv[0] == "migrate-agents":
+        rest = [a for a in argv[1:] if a != "--write"]
+        if len(rest) <= 1 and len(argv) - len(rest) <= 2:
+            return migrate_agents(*rest, write="--write" in argv[1:])
+    if argv and argv[0] == "validate":
+        code = process_format.run(argv[1:])
+        if code is not None:
+            return code
+    if argv and argv[0] in ("list", "new", "archive"):
+        code = process_cli.run(argv)
+        if code is not None:
+            return code
+    if argv and argv[0] == "config":
+        code = settings.run(argv[1:])
+        if code is not None:
+            return code
+    if argv and argv[0] == "integrations":
+        code = integrations.run(argv[1:])
+        if code is not None:
+            return code
+    if argv and argv[0] == "check":
+        code = integration_run.run(argv[1:])
+        if code is not None:
+            return code
+    if argv and argv[0] == "import":
+        code = import_openspec.main(argv[1:])
+        if code is not None:
+            return code
+    if argv[:2] == ["sync", "pull"]:
+        code = layout.main(argv[1:])
+        if not os.path.exists(os.path.join(layout.REPO, ".git")):
+            print("source is the installed package: the edit is lost on upgrade, move it to a clone")
+        return code
+    if argv[:1] in (["-h"], ["--help"], ["help"]) or argv[1:2] in (["-h"], ["--help"]):
+        print(COMMANDS)
+        return 0
+    if argv:
+        print("solo-sdd: wrong command or arguments: " + " ".join(argv), file=sys.stderr)
+    print(COMMANDS)
+    return 2

solo_sdd/data/ALGORITHM.md

@@ -0,0 +1,211 @@
+# Solo SDD: the algorithm
+
+Spec-driven development for one person or a team, with any coding agent (Claude Code and Codex today). The user sets the goal and accepts the result. The agents run the work themselves: from the plan to code merged into main, without questions along the way. The base is solo-sdd's own process tree `solo-sdd/` and its commands (`solo-sdd new`, `validate`, `list`, `archive`); the skills from `skills/` work on top of them. A project still on `openspec/` moves with `solo-sdd import openspec`.
+
+How the repository is organised and how to deploy it is in [README.md](README.md). The third-party files the repository ships are listed in [SOURCES.md](SOURCES.md). Why the rules are worded the way they are is in [LESSONS.md](LESSONS.md).
+
+## Principles
+
+1. **The specification is the source of truth.** Behaviour changes together with the spec, in one change. Code that diverges from the spec counts as a defect, even if the tests are green.
+2. **A small change.** One result the user can check themselves, one area of code, at most 10 tasks. If it comes out bigger, it is several changes linked through `Depends On`.
+3. **A property, not a method.** The spec says what must be true ("git history does not change"), not how to check it ("look for the substring push"). The implementer chooses the method.
+4. **Proof, not a report.** Readiness is confirmed by observations: a test that fails on the previous code, and a live scenario in what a person sees. Green tests, a report by the author or a subagent, "the function was called" do not count as proof.
+5. **No questions along the way.** The agent resolves an ambiguity itself and records the decision. Asking is allowed only before three things: a paid call, deleting or overwriting data, an action on prod. The question names what will happen, how many calls and what amount.
+6. **A blocker does not stop the work.** First look for a workaround: mocks, old data, `.env`, a neighbouring service. No workaround: what is unchecked goes into `verification.md` and `docs/waiting.md`, the rest gets closed.
+7. **Code is written by whoever holds the plan.** Every handoff between agents loses precision, so the lead agent writes the code itself. Subagents are for independent acceptance and heavy reading. Review is done by an agent that did not write this code.
+8. **Nothing is invented.** Values the source knows (CLI, API, database) are asked from the source. An honest "could not determine" is better than a plausible value.
+9. **Cheap where a mistake is easy to notice.** Search, reading logs and test output run on cheap models; code, review and acceptance on the main one. First the effort changes (medium by default, low for mechanics, higher if stuck), the model only when effort did not help. Paid calls to the product model in tests and runs go to the cheapest models and with consent. Heavy reading goes to a search subagent (Explore), so the lead's context does not get compacted.
+10. **"Done" = archived, checked live, merged.** If any of the three is missing, the status is "not done" with what is missing.
+
+## Cycle
+
+```
+ 0 project-init ─► 1 context-resume ─► 2 evidence-research (when needed)
+                                                   │
+ 9 spec-audit ◄─ 8 ship ◄─ 7 closing ◄─ 6 proof ◄─ 5 spec-next ◄─ 4 spec-analyze ◄─ 3 spec-plan
+ (every 5 archives)                        ▲
+                                         debug-profile, ui-check, agent-quality
+```
+
+Cross-cutting skills at any stage: `work-status` (five lines about the state), `context-resume` (after a pause, a context compaction or an agent switch).
+
+### 0. The project is ready for agents: `project-init`
+
+Once per project. It creates `AGENTS.md` (project rules: commands, map, boundaries and invariants, checks), `CLAUDE.md` with the line `@AGENTS.md`, the process tree `solo-sdd/` by `solo-sdd init` with `solo-sdd/project.md` (language, mode and an "Intent"), `.env.example`, README.
+
+In a repository that already has code it also writes the codebase map `docs/codebase/` (`STACK.md`, `ARCHITECTURE.md`, `CONVENTIONS.md`, `CONCERNS.md`): four cheap subagents, every statement names a path, each file stamped with the commit; the `CONCERNS.md` items are candidates for `spec-plan`. `/project-init map` refreshes it.
+
+**Gate G0:** `solo-sdd validate --all` passes; every command from the `AGENTS.md` table actually runs; the project comes up by the README in a clean shell.
+
+### 1. Context: `context-resume`
+
+When returning to a project, after a context compaction or on an agent switch. It reads the project rules, `handoff.md`, `verification.md` of open changes, `git status` and the history by the words of the task. The output is a map: the goal, the source of truth, the last confirmed state, the user's decisions, blockers, the next step. A fact from history is checked against files and the service. If they diverge, the current state counts as right.
+
+### 2. Research and decision: `evidence-research`
+
+Only when the plan cannot be written without it: choosing a technology, a service or an approach. `evidence-research` gives a table of options by the user's constraints, every fact with a source and a date. A disputed decision goes the same way: the options side by side on checked facts, the choice and its reason. The result goes into `spec-plan` as input.
+
+### Light path: no change
+
+A code edit takes the light path when it changes no behaviour a main spec describes, adds no dependency, touches no data, migration or deploy, and changes at most `process.light-path.max-files` files (default 3); `process.light-path: off` forbids it. The edit, the project's tests, a live check of the edited place and one commit `light: <the request>` are the whole record; `spec-plan` coverage names such an item with its commit, `work-status` and `report` count these commits apart from changes. Anything outside the bounds, and a bug in behaviour a spec describes, goes through a change.
+
+### 3. Plan: `spec-plan`
+
+Input: a plan, a bug list, the result of a discussion. Output: a queue of small changes. No code is written, except the light path items, after the plan commit.
+
+- A unit fits if it has one checkable result, one area of code, at most 10 tasks and a live check scenario. Bugs are grouped by a common cause, not "one bug, one change".
+- A unit that leads away from the "Intent" of `solo-sdd/project.md` does not become a change and goes into the report.
+- `solo-sdd new <id>` lays out the change; the artifacts are written in the order proposal → specs → verification → tasks by the "Writing rules" of `spec-plan` (see "Change artifacts").
+- Whatever waits for a person, access or paid consent does not become a task. It is `Needs` in `verification.md`. A change made up entirely of such conditions gets a `WAITING` file.
+- Every input item is matched with a change or the light path. Any other item without a change counts as an error.
+- A bug with a found cause takes the short track (the "Bug fix" section in `spec-plan`): the reproduction and the place of the cause in the proposal, the bug scenario is added to the spec, the first task is a failing test for this scenario, at most 5 tasks, side edits in Out of Scope. Cause not found: `debug-profile` first.
+- A UI change starts What Changes with a Design Read line from `DESIGN.md` (no `Dial` line with three numbers means dials 1/1/1 and "draft without direction"); the Live Scenario is a list "element → action → result"; the user's business facts (numbers, reviews, customers) are placeholders `[data needed: …]`.
+
+**Gate G1:** `solo-sdd validate --all`; then `spec-analyze` on every created change (stage 4); full coverage of the input.
+
+After G1 the folders of created and changed changes go in one commit `change: <id>, …`, without other edits. If `solo-sdd/changes` is ignored, there is no commit, and the report says "plan outside git".
+
+### 4. Check before code: `spec-analyze`
+
+Before the first task of every change. The spec is checked against itself while there is no code: a hole in `tasks.md` costs one line, after implementation a rework.
+
+Passes:
+
+| # | Pass | What it looks for |
+|---|---|---|
+| 1 | Coverage | A requirement or scenario without a task and a test; a task without a requirement |
+| 2 | Solo frame | An empty Out of Scope; an unarchived Depends On; a retelling instead of a quote in Source; more than 10 tasks; waiting for a person in tasks; a Live Scenario that does not reach what the user sees |
+| 3 | Checkability | A task without an observable criterion |
+| 3a | Executable properties | An invariant, round trip or idempotence checked only by examples |
+| 4 | Consumer | A new field, module or value that nobody reads |
+| 5 | Ambiguities | Empty, erroneous and partial cases; "no data" versus "not read"; a repeat; what the user sees in each outcome; term drift; `TBD` |
+| 6 | Wording | A method instead of a property; line numbers instead of structure; hard-coded values; words without a measure |
+| 7 | Consistency | A contradiction with the main spec; a decision in design without a task; a task uses what appears later; drifting from the intent |
+| 7a | Requirement compatibility | Requirements that are true one by one and unsatisfiable together; incompatible constraints; an undescribed combination of conditions; a hidden assumption |
+
+Checks derived from the defects of a specific project live in its `solo-sdd/analyze.md` (laid out by `solo-sdd init`). The skill picks them up itself.
+
+The agent fixes CRITICAL and HIGH findings in the artifacts and writes the decisions into `Decisions Without Owner`. Code does not change in this pass.
+
+**Gate G2:** no open CRITICAL and HIGH; everything from `Depends On` is archived. Otherwise the change is not ready, and `spec-next` takes another.
+
+### 5. Implementation: `spec-next`
+
+One run closes one change, from selection to archive.
+
+1. Step 0: a project with `openspec/` and no `solo-sdd/` stops here with the next step `solo-sdd import openspec`; the skills never import by themselves.
+2. Selection: the named change; else the one with the most done; else the next one with closed dependencies. A change with a `CLAIM` file (taken by another agent) or `WAITING` is skipped.
+3. Claim: `solo-sdd/changes/<id>/CLAIM` in the main project folder with the line `<agent> <date>`; Claude adds `session=<session id>` (`$CLAUDE_CODE_SESSION_ID`), by which the write hook recognises its own `CLAIM`. The hook itself places the marker only on a `tasks.md` edit that checks a new task: analysis and audit that edit artifacts do not take the change.
+4. Check: `spec-analyze` (stage 4).
+5. The lead agent does the tasks from `tasks.md` itself, including code. Subagents are only for acceptance (item 7) and heavy reading (`Lookup:`, Explore). Executors only if the user named `codex-orchestration` (Codex CLI); then the orchestration rules apply:
+   - Split by file ownership. Independent units go in a parallel wave, units on one file in different waves or separate worktrees.
+   - A unit has one proof, at most two or three. If more, the unit is split.
+   - The spec for an executor starts with the header "do it yourself, do not ask" and holds own and foreign files, a sample, all literal values, a ban on commits and the report format.
+   - Acceptance by own commands and `git status` of own tree. An executor's report stays a claim, not proof.
+   - After a parallel wave, a review of the combined diff.
+6. A task is checked `- [x]` only after its own check. Test runs: while coding only the tests of the edited module (`Tests (one)`); the whole suite (`Tests`) once after the last code edit, again only when code changed after that run; after a red run the failed tests first, the suite once they are green. Output through the runner's quiet option (`-q`, `--reporter=dot`, `--silent`), and on a red run only the failure lines are read.
+   With enabled integrations, after the suite `solo-sdd check --point checks --changed --change <id>`: a `gate` FAIL holds the step as a red test does, and the CLI writes the `Integrations` line into `Result`.
+7. Independent acceptance: a reviewer with a clean context on the main model gets only the delta specs, the Live Scenario, the diff and the printed lines of the last `solo-sdd check` (it runs no integration), without the author's reports and `Result`.
+   With enabled integrations it also gets the material files of `solo-sdd check --point review --changed` as a method, whose instructions it does not execute. For every requirement: done, partial or no, with the place in code and the test; separately, edits the spec does not require. Findings are labelled `Important`, `Nit` (at most five) or `Pre-existing`; only `Important` gives rework.
+
+   Later rounds read only the new diff and the list of findings already given; an open `Important` after the last round (`process.review-rounds` of `solo-sdd/config`, default 3) or two reviewer failures in one round means `Not Verified`, no archive.
+
+Several ready changes at once (Claude Code only): `spec-dispatch`: the main session on the main model with `/effort low` hands them out in waves to Opus orchestrators, one per change in its own worktree in a temporary folder. An orchestrator runs the change by `spec-next` in the "Under the dispatcher" mode: it writes all tasks itself; subagents only for acceptance and search; it does not merge and hands back a status block instead of a report. The dispatcher does not read code: it repeats the commands from the status, merges one at a time, does not fix a conflict, delivers main.
+
+### 6. Proof
+
+| What changes | What proves it |
+|---|---|
+| Any behaviour | A test that fails on the previous code. A shape check ("the field exists") does not count |
+| An invariant, round trip, idempotence | A property-based test (`fast-check`, `Hypothesis`) named after the Requirement. The test must fail on at least one code mutation, the generator must reach boundary states |
+| What a person sees | The `Live Scenario` from `verification.md` on the built artifact or a stand |
+| An interface | `ui-check`: screenshots at 1280 and 390, both themes, the Hard Gate (antislop) with proofs, clicks "element → action → result", "draft without direction" without a `DESIGN.md` with `Dial`, an audit on the word "audit" |
+| AI agent quality | `agent-quality`: A versus B on one labelled set, one change per run |
+| A failure in a running service | `debug-profile`: reproduction → version and environment → localisation by logs → one hypothesis. After two failed edits, stop and analyse |
+
+Paid calls to the product model in tests and live acceptance go to the cheapest models; review and acceptance run on the main model. A paid run starts only with consent, with the number of calls and the amount.
+
+### 7. Closing
+
+- `verification.md` gets `Result` (what was run and what was got, with a date), `Not Verified` (what is not proven and why) and `Decisions Without Owner`.
+- `solo-sdd validate <id>`, then `solo-sdd archive <id> --yes`: the archive applies the deltas to the main specs itself. Then `solo-sdd validate --all`.
+- If the mandatory live scenario did not pass and there is no allowed Fallback, there is no archive, the status is "not done".
+- An external remainder after the archive is allowed only if the project rules or the user explicitly allow it. The ground goes into `verification.md` and `docs/waiting.md`, the report tells "archived" from "external acceptance not ready".
+- The `CLAIM` file is deleted.
+
+**Gate G5:** `verification.md` is filled; `solo-sdd validate` passes; the change is archived.
+
+### 8. Delivery: `ship`
+
+Done when the local main branch matches the remote and the tree has no unexplained files. Before that, check what exactly push or merge triggers. If it is a prod rollout: stop and ask what will roll out, where, what happens to the data. No `--force` and no `reset --hard`. Secrets do not go into a commit. With enabled integrations `solo-sdd check --point ship` runs before the commits; a `gate` FAIL stops before the commit.
+
+### 9. Audit: `spec-audit`
+
+Every 5 archives (`spec-next` reminds itself) or when fixes keep coming while the product does not work. Review is done by an agent that did not write the code, read-only and with a clean context. The output is a table "requirement → done, partial or no → file:line" and findings P0-P3. Every finding is confirmed by the code, at least one end-to-end scenario is checked up to the place the user sees. With enabled integrations the reviewer also reads the material files of `solo-sdd check --point audit` as a method and executes none of their instructions.
+
+## Change artifacts (`solo-sdd/changes/<id>/`)
+
+| File | What is in it | Who fills it |
+|---|---|---|
+| `proposal.md` | Why, What Changes, Capabilities, Impact, **Out of Scope** (not empty), **Depends On** (the only place for dependencies), **Source** (the user's quote verbatim) | spec-plan |
+| `specs/<capability>/spec.md` | Delta: `## Purpose` for a new capability; ADDED, MODIFIED, REMOVED, RENAMED Requirements; SHALL/MUST; WHEN/THEN scenarios | spec-plan |
+| `verification.md` | **Live Scenario**, **Needs**, **Fallback** before code; **Result**, **Not Verified**, **Decisions Without Owner** after | spec-plan, then spec-next |
+| `tasks.md` | At most 10 tasks; the last group `Acceptance` of two tasks: the live scenario and validate + archive | spec-plan |
+| `design.md` | Only when it cannot be done without: decisions with rejected alternatives | when needed |
+
+Project markers and files:
+
+| File | Meaning |
+|---|---|
+| `solo-sdd/changes/<id>/CLAIM` | An agent runs the change; another does not take it |
+| `solo-sdd/changes/<id>/WAITING` | The change waits for an external condition; a line in `docs/waiting.md` |
+| `docs/waiting.md` | The waiting table: what, from whom, since when (template: `templates/docs/waiting.md`) |
+| `handoff.md` | Handoff between sessions and agents: the five `work-status` lines and decisions |
+| `docs/debug-profile.md` | What runs where, logs, config, what must not be touched without consent |
+| `solo-sdd/analyze.md` | `spec-analyze` checks derived from the defects of this project |
+
+## Gates
+
+| Gate | When | Who checks | What | On failure |
+|---|---|---|---|---|
+| G0 | After `project-init` | The lead agent | validate, the commands from AGENTS.md run, the project comes up by the README | Fix the project or the README |
+| G1 | After `spec-plan` | The lead agent | validate, analyze, input coverage | Split or complete the changes |
+| G2 | Before code | `spec-analyze` | No CRITICAL and HIGH, dependencies archived | Fix the artifacts; the change is not taken |
+| G3 | After every task | The lead agent, by own commands | The diff, the task's checks, `git status` of own tree | Rework until the checks are green |
+| G4 | Before closing | The lead agent and an independent reviewer | The test failed on the previous code; the property test catches a mutation; the Live Scenario passed; the reviewer has no open `Important` | "Not done", Not Verified |
+| G5 | Closing | The lead agent | verification.md, `solo-sdd validate`, archive | Do not archive |
+| G6 | Delivery | `ship` | main = origin/main; deploy only with consent | Stop before the deploy |
+| G7 | Every 5 archives | An agent that did not write the code | Requirement ↔ code, an end-to-end scenario | P0 and P1 are fixed if the task allows the fix; otherwise a report to the user, who can pass it to `spec-plan` |
+
+## Roles
+
+| Role | Does | Does not |
+|---|---|---|
+| User | Gives the goal, Source and Intent; accepts the result; agrees to money, deletion and prod | Does not carry context between agents, does not answer technical questions along the way |
+| Lead agent | Plans, writes code, keeps the artifacts, closes the change | Does not accept own work; does not trust reports |
+| Executor (Codex, by the user's choice) | Does one unit in its own files and reports in the given form | Does not touch foreign files, does not commit, does not invent values |
+| Reviewer | Reads code and spec with a clean context, read-only | Does not edit what it found |
+| Search (Explore) | Reads many files and returns a digest | Does not edit and does not make decisions |
+
+Claude Code and Codex are equal: both work by the same rules (`~/AGENTS.md` = `~/.codex/AGENTS.md` = `~/.claude/CLAUDE.md`) and the same skills. They differ only in the tool for subagents and orchestration.
+
+## When to run what
+
+| Situation | Skill |
+|---|---|
+| A new folder or a repository without rules | `project-init` |
+| "Let's continue", after a pause or an agent switch | `context-resume` |
+| "What to choose", comparing technologies or services | `evidence-research` |
+| A disputed decision between options | `evidence-research` |
+| A plan, a bug list, the result of a discussion → into work | `spec-plan` |
+| A bug with a found cause | `spec-plan`, the "Bug fix" section; cause not found: `debug-profile` first |
+| Before the code of a change | `spec-analyze` |
+| "Implement the next spec", "finish the change" | `spec-next` |
+| Several ready changes, "hand them to orchestrators", the main session only accepts statuses (Claude Code) | `spec-dispatch` |
+| The interface changed | `ui-check` |
+| Text for people in the product | `copy-check` |
+| A prompt, model or retrieval of an AI agent changes | `agent-quality` |
+| A service does not work, the cause is not obvious | `debug-profile` |
+| Commit, push, PR, merge | `ship` |
+| "Status?" | `work-status` |
+| Review, audit, "why does nothing work" | `spec-audit` |

solo_sdd/data/global/AGENTS.md

@@ -0,0 +1,132 @@
+# Global work rules: `~/AGENTS.md`, `~/.codex/AGENTS.md`, `~/.claude/CLAUDE.md`
+
+Shared by Claude Code and Codex. The three copies above are deployed from the solo-sdd repository (`global/AGENTS.md`): edit in the source that `solo-sdd status` names (the `source:` line), and run `solo-sdd install` (from a clone, `python3 sync.py push`). Pull an edit made in one of the copies with `solo-sdd sync pull global/AGENTS.md`.
+
+## 0. Rule order
+
+1. At the start of work in any folder, find the local project rules: `AGENTS.md` and `CLAUDE.md` in the current folder and above up to the repository root, `solo-sdd/project.md` (a project with only `openspec/` moves by `solo-sdd import openspec`), `docs/status.md`. Read them yourself, without a reminder. Claude does not pick up `AGENTS.md` automatically, Codex does not pick up `CLAUDE.md`, so read both.
+2. Local rules exist: on any divergence they apply. This file covers only what the local rules are silent about.
+3. No local rules: work entirely by this file. If the work in the folder is more than a one-off edit, suggest `/project-init` in one line.
+4. A direct instruction of the user in the current chat wins over both the local and the global rules.
+
+## 1. Communication
+
+- Reply in the language the user writes in, including the final report and comments for the user.
+- Briefly. The result first, then the details. Asked for "briefly": 2-3 sentences.
+- Instructions for the user: numbered steps, with the exact name of the button or field ("where to click").
+- Terminal commands: one block that can be pasted whole; with `cd` to a full path; no comments on the same line as a command.
+- Before asking or saying "this does not exist", reread the chat and the project folder: the user may have given it already. When returning to a project or switching agents: `/context-resume`.
+
+## 2. Autonomy
+
+- Do not ask clarifying questions during the work. Make a reasoned decision and list the decisions made in the report.
+- Ask only before: paid requests, deleting or overwriting data, actions on prod. The question names what exactly will happen, the number of requests and the amount.
+- Whatever you can do yourself, do yourself: running, checking, clicks in the browser, reading logs. Hand manual steps to the user only when you have no access, and say which access exactly.
+- Do not stop while there are unfinished items and no real blocker.
+
+### Commands and stopping processes
+
+- If a command must not get input, close stdin with `< /dev/null`. Keep pipes, heredocs and intended input; do not run bare `cat`, `read` or interactive interpreters without an input source.
+- Run servers and other long-lived processes as managed background tasks and keep their id. Run ordinary builds and tests with a bounded timeout.
+- After a timeout, first check the task's state with the standard tool. Do not assume all child processes have ended, and do not "clean them up" by name.
+- Do not use `pkill`, `killall`, an arbitrary `kill` (including a numeric PID), `osascript`, `launchctl` or `shutdown` to stop things. Use the built-in stop of the specific task by its id. Managing its processes is the job of the launch environment, which knows what processes it created.
+- Do not force a sandbox on all projects: check that the sandbox is compatible with the project's tests before changing the mode. If the sandbox is on for a project on macOS, dev ports need `sandbox.network.allowLocalBinding: true`. Do not install a build into `/Applications` without separate consent.
+
+## 3. What "done" means
+
+- "Done" depends on the kind of work:
+  - code: done + checked by tests + checked live on a real scenario + recorded by the project rules (changes: validate, archive; git: commit, push, merge);
+  - analysis or research: a conclusion, sources with dates, separately what is not confirmed; files do not change;
+  - text: facts checked, form and length fit the reader, one ready version;
+  - prod: the change is rolled out with consent and checked by the same scenario on prod.
+- Git and the change cycle (`solo-sdd/`) are mandatory where the project and the task provide for them. A one-off text or analysis does not need their cycle.
+- Light path: a code edit needs no change when it changes no behaviour a main spec in `solo-sdd/specs/` describes, adds no dependency, touches no data, migration or deploy, and changes at most `process.light-path.max-files` files. Read `solo-sdd config get process.light-path` and `solo-sdd config get process.light-path.max-files`; no `solo-sdd/` tree or no command: on and 3. Then: the edit, the tests of the edited module, the suite once after the edit, a live check of the edited place, one commit `light: <the request>` (under `delivery.mode: pr` the PR title starts with `light:`). Outside the bounds, a bug in behaviour a spec describes, or `off`: a change.
+- Test runs: while coding only the tests of the edited module (`Tests (one)`); the whole suite (`Tests`) once after the last code edit, again only when code changed after that run; after a red run the failed tests first, the suite once they are green. Quiet output (`-q`, `--reporter=dot`, `--silent`); on a red run read only the failure lines.
+- Tests prove behaviour: a behaviour a live stand proves gets no second test (a required property test and a bug's regression test excepted); a new case is a row of the existing test; no tests for getters, DTOs, configuration, thin wrappers, private functions a scenario test reaches, one-off scripts or what a CI step checks. Doubles only for external I/O (the network, paid APIs) and the clock; own storage gets a temporary real one or an in-memory fake; the module under test is never mocked. An existing assertion changes or goes only when the behaviour it checks changes on purpose (a MODIFIED or REMOVED requirement); a change of setup, cost or layout keeps every assertion.
+- If any of this is missing: write "not done" and what is missing. Green tests by themselves do not mean "done".
+- The report names the checks done and, separately, the ones not done with the reason.
+- The same edit did not help twice: stop and find the cause instead of a third attempt the same way.
+
+## 4. Blockers
+
+- No key, access or data: first look for a workaround: mocks, old project data, `.env`, neighbouring services, documentation.
+- No workaround: record what stayed unchecked and what is needed for it (in a change, `verification.md` and `docs/waiting.md`), and close everything else.
+
+## 5. Status and waiting
+
+- Before waiting longer than 2 minutes, say what you wait for and how long.
+- In long work, give a status line after every stage.
+- Answer a status question with the `/work-status` skill.
+
+## 6. Task boundaries
+
+- Asked to analyse, describe or assess: change nothing.
+- Asked to fix: change only the named places. Do not rewrite from scratch and do not delete previous versions.
+- Work outside the current task becomes a separate task, not done along the way.
+- Do not hard-code lists and values that can be got from the source. Temporary hard-coding only on a direct request.
+
+## 7. Money and resources
+
+- Search, logs and test output run on cheap models; code, review and acceptance on the main one. Effort first, then the model.
+- Paid calls to the product model in tests, acceptance and experiments run on the cheapest models.
+- Do not start paid requests without approval.
+- An external service is needed: free options and free tiers first.
+- Watch the context: hand heavy reading to a search subagent (Explore), write code yourself.
+
+## 8. Secrets and data
+
+- Secrets live only in `.env`. Do not print them and do not ask to send them in chat: create an empty field and name it.
+- Keys, certificates and personal data do not go into git or logs.
+- Before an operation on a database or a server, say what will happen to the existing data.
+- Use a fact about experience, a metric or a number from history together with its source, date or period and status: confirmed | from an old record | not checked. Apply new calculation rules to new records; recalculating accumulated data only on a direct request.
+- All project files are kept inside the project folder.
+
+## 9. Two agents in one project
+
+- The project has one working folder. Create your copies and worktrees in the built-in Claude Code worktree (`claude --worktree <name>`, `EnterWorktree`, `isolation: "worktree"` of a subagent: the copy goes into the project's `.claude/worktrees`; this folder must be in `.gitignore`) or in a temporary folder (`git worktree add "${TMPDIR:-/tmp}/wt-<name>"`) and delete them after yourself. Codex uses only a temporary folder: `codex --worktree`, `/worktree` and the `create_worktree` tool put the copy into `~/.codex/worktrees`.
+- Before an edit, check `git status`: another agent may be working next to you. Do not roll back others' changes.
+- Before taking a change, check for `CLAIM` (taken by another agent) and `WAITING` (waits for an external condition) files in its folder. If either is there, take another.
+- An independent review is done by the agent that did not write the code.
+
+## 10. Orchestration
+
+- You write the code yourself: every handoff between agents loses precision. Subagents are only for independent acceptance and heavy reading (Explore). Independent changes run in parallel through `spec-dispatch`.
+- Codex executors only when the user named the skill `codex-orchestration`.
+- Plan through `/spec-plan`, debug through `/debug-profile`. In a project with `solo-sdd/` a plugin's own cycle of tests, verification, per-task subagents and code review is not used: `spec-next` and `ship` set the cycle.
+
+## 11. Project mode
+
+- The mode is set in the local rules: `demo` or `prod`. If not set, decide by the task: a demo, a defence, a prototype, an MVP mean `demo`.
+- `demo`: no docker and no deploy, invented data, one demo script, the run command as the first line of the README.
+- `prod`: logs cover every stage so that the cause of a failure can be found from them; there is a deploy instruction.
+
+## 12. Interface
+
+- A product interface is handed over after checking it against the mockup and clicking every changed element in the browser, on desktop and on a phone. Skill `/ui-check`.
+- `/ui-check` passes the Hard Gate (antislop rules) with a proof in every line. No `DESIGN.md` with a `Dial` line: the interface is marked "draft without direction".
+- A personal HTML report without a request for external publication: check display and clicks on desktop; an adaptive check is not required.
+
+## 13. Git, if the local rules are silent
+
+- After checked work: commit and push. Merge an open PR yourself only when the project's settings let the agent merge (`solo-sdd config get delivery.merge-by` is `agent`, or no `solo-sdd/` tree), then update the local main branch; with `human` stop at a green PR: a person merges.
+- No `--force` and no `git reset --hard`.
+- If push or merge triggers a prod deploy (CI, a hook, hosting autodeploy), stop before them and ask. An open PR does not mean a checked prod.
+- Skill `/ship`.
+
+## 14. Skills
+
+`/spec-plan`: a plan or a bug list into a queue of small changes · `/spec-analyze`: a check of a change before code · `/spec-next`: a change from selection to archive · `/ship`: commit, push, PR, merge · `/work-status`: five lines about the state · `/spec-audit`: an independent check of code against the spec · `/ui-check`: a check of the interface against the mockup · `/copy-check`: product texts for people without AI signs or invented facts · `/project-init`: preparing a new project · `/context-resume`: restore the context before work · `/debug-profile`: debugging a service or a bug in code · `/agent-quality`: AI agent quality by comparison on a set of cases · `/evidence-research`: comparison and choice on checked facts
+
+Manual commands, only when the user calls them: `/relay`: another agent's report into work · `/blockers`: blockers and findings into separate changes · `/report`: a summary for a period · `/health`: whether the project's integrations are alive · `/changes`: a table of change states
+
+Choose a skill by the goal and the expected result, not by a matching word: "analyse" can be about code, logs or a text. If a tool a skill refers to is not in the current environment, take a fallback source (local history, project files, a notes vault) and do not pass off missing data as a fact.
+
+The whole algorithm, with all stages and gates: `~/.local/share/solo-sdd/ALGORITHM.md`. The skills of this algorithm are edited in the source from `solo-sdd status`, in `skills/`, not in the agent folders: `solo-sdd install` deploys them and does not overwrite an edit made in place, but shows it.
+
+## 15. Lessons
+
+- The user corrected you in a way that applies beyond the current task, or you fixed a bug and found its cause: without asking, write one imperative sentence about the class of cause, not the symptom, with no file or line ("Every async call in a handler is awaited", not "add await in api.py"), into the `## Lessons` section at the end of the project's `AGENTS.md`, creating the section if it is missing. This is part of any task, also under "change nothing" or "only the named places"; if the user forbade edits, the report gives it as `Lesson (not written): <sentence>`. A remark about the current diff only ("rename this variable") is not a lesson.
+- First search `## Lessons` and the rest of that `AGENTS.md`: a lesson an existing line covers refines that line instead of adding one. The section holds at most 20 lines; a 21st means merging or generalising the closest lines in the same edit, also without asking.
+- No `AGENTS.md` in the project: create none; the report gives the lesson as `Lesson (no AGENTS.md): <sentence>`.
+- Never write a lesson into the installed global rules (`~/AGENTS.md`, `~/.codex/AGENTS.md`, `~/.claude/CLAUDE.md`); a lesson about the solo-sdd process itself goes only into the report as `Lesson for solo-sdd: <sentence>`.
+- The report names every line written or refined in `## Lessons` and its file.

solo_sdd/data/global/model-policy.json

@@ -0,0 +1,14 @@
+{
+  "_comment": "Model policy for the work_hooks.py guard and stop hooks. Source of the list: ~/.codex/models_cache.json (affordable/fast descriptions) on 2026-10-15. Subagent roles (review, orchestrator, implement, lookup) are taken from an explicit tag at the start of the description (case-insensitive; the orchestrator tag is the word followed by a space or a colon). A reviewer (review) runs without model or on a model from main: review and acceptance are judgement, they run on the main model. Only the owner allows bypassing the model rules: SOLO_SDD_EXPENSIVE_OK=1 in the Claude Code environment. test_markers keeps Russian test words as \\u escapes: prompts may be Russian, the repository holds no Cyrillic. The deployed copy ~/.claude/hooks/model-policy.json is yours: edit the model lists and the browser key there. browser.tools (tool name prefixes), browser.skills (skill names) and browser.bash (plain substrings of a Bash command) add to the hook's built-in browser signs of the stop interface check and cannot remove one; a part that is not a list of non-empty strings adds nothing and writes an errors.log line. install, update and sync.py push skip an edited copy (skipped ... edited in place) and sync.py status shows it as drift, so a newer shipped list is not taken while it is drift. To take it: from a clone, python3 sync.py push --force (the old copy is saved under ~/.local/share/solo-sdd/backup/); from the package, move the copy aside, run solo-sdd update (created) and carry your edits over.",
+  "cheap": ["luna", "terra", "reserve", "haiku"],
+  "expensive_always": ["astra"],
+  "expensive": ["astra", "sol", "opus", "fable"],
+  "main": ["opus", "fable"],
+  "roles": {"review": ["Review:"], "orchestrator": ["Orchestrator ", "Orchestrator:"], "implement": ["Implement:"], "lookup": ["Lookup:"]},
+  "browser": {
+    "tools": ["mcp__claude-in-chrome__", "mcp__agent-browser__", "mcp__peekaboo__"],
+    "skills": ["ui-check", "agent-browser", "claude-in-chrome", "webapp-testing", "run", "web-perf"],
+    "bash": ["agent-browser", "playwright", "puppeteer", "--headless", "chrome-devtools", "screencapture", "--remote-debugging-port", "json/version", "webSocketDebuggerUrl"]
+  },
+  "test_markers": "(?i)(\\btests?\\b|pytest|vitest|jest|node --test|acceptance|e2e|smoke|eval\\b|benchmark|probe|\u043f\u0440\u0438\u0451\u043c\u043a|\u043f\u0440\u0438\u0435\u043c\u043a|\u043f\u0440\u043e\u0433\u043e\u043d|\u0442\u0435\u0441\u0442)"
+}