@cerebriline/core 4.100.240 → 4.100.242

package/assets/skills/run-project/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: run-project
+description: >-
+  Runs the project open in the workspace and opens it: starts it the way the
+  repo defines (its Docker compose stack or image, or its own start or dev
+  command), waits until it answers, and opens the app in the default browser.
+  Use when the user asks to run, start, launch or open the project or the app.
+disabled: true
+---
+
+# Skill: Run the Current Project
+
+"Run the project" means: get it running the way this repo intends, confirm it answers, and put it in front of the user. Every value is **discovered from the repo**; none is assumed.
+
+Related skills, used when they are enabled; each also works alone:
+
+- `build-project` builds the project and its image.
+- `docker-compose-deploy` starts and verifies the containers.
+
+## Step 0: Decide how this repo runs
+
+Look, in this order, and take the first that applies:
+
+1. **What the repo says.** `README*`, `docs/`, an `AGENTS.md` or similar. A documented way to run it is the answer, including when it is not Docker.
+2. **A compose file** (`docker-compose*.yml`, `compose*.yml`) → run it as containers.
+3. **A Dockerfile and no compose file** → run the image as one container.
+4. **No Docker files** → run it natively, with the repo's own command:
+
+| Found | Start command |
+|---|---|
+| `package.json` | the `dev` script, else `start`, with the manager whose lockfile exists |
+| `*.csproj` of a web or console app | `dotnet run --project <path>` |
+| `manage.py` | `python manage.py runserver` |
+| a Python app with `uvicorn`, `flask` or `streamlit` in its dependencies | that tool's run command, on the app module the repo names |
+| `go.mod` with a `main` package | `go run .` or `go run ./cmd/<name>` |
+| `Cargo.toml` with a binary | `cargo run` |
+| `pom.xml` / `build.gradle*` with Spring Boot | `./mvnw spring-boot:run` / `./gradlew bootRun` |
+
+If the project is not something that serves a page (a library, a command-line tool, a batch job), run it the way the repo documents, show its output, and skip the browser steps. If there is nothing to run, say so.
+
+## Step 1: Start it
+
+**Containers (cases 2 and 3).** Follow the `docker-compose-deploy` skill if it is enabled. Otherwise:
+
+```
+docker info                                   # Docker must answer first
+docker compose up -d                          # compose stack; builds what is missing
+# or, one container from a Dockerfile:
+docker build -t <image-name>:dev <build-context>
+docker rm -f <container-name>                 # only a container this skill created earlier
+docker run -d --name <container-name> -p <host-port>:<container-port> <image-name>:dev
+```
+
+Add `--build` to `docker compose up -d` when the source changed since the image was built.
+
+**Natively (case 4).** Install dependencies first if they are missing (`node_modules` absent, no virtual environment), with the lockfile as it is. Then start the command **so that it keeps running**: a dev server never exits, so start it in the background or detached and do not wait for it to finish. Keep its output where it can be read back.
+
+In both cases, if the project needs configuration it does not have (a required variable in the compose file, a `.env.example` with no `.env`), say what is missing and ask. Do not invent secrets.
+
+## Step 2: Find the address
+
+| Running as | Where the port is |
+|---|---|
+| compose | the **host** side of the service's `ports:` (`"8080:80"` → 8080); `docker compose port <service> <container-port>` prints the real one |
+| one container | the host port given to `-p` |
+| natively | the line the server prints on start (`Local: http://localhost:5173`, `Now listening on: ...`), else the framework's default, else the repo's config |
+
+With several services, the one to open is the web front end: the service named `web`, `frontend`, `app` or `ui`, or the one whose port the README names. Open the path the README names if it is not `/`.
+
+## Step 3: Wait until it answers
+
+Starting is not running: a request sent the moment the process starts fails. Ask until it answers; the `--retry` options make curl do that for up to about half a minute:
+
+```
+curl -s -o /dev/null -w "%{http_code}" --retry 15 --retry-delay 2 --retry-all-errors http://localhost:<port>/          # bash, zsh
+curl.exe -s -o NUL -w "%{http_code}" --retry 15 --retry-delay 2 --retry-all-errors http://localhost:<port>/            # PowerShell, cmd
+```
+
+Any `2xx` or `3xx` is up; `401` and `403` also mean a server is answering. If nothing answers, read the output (`docker compose logs --tail 100 <service>`, `docker logs --tail 100 <container-name>`, or the dev server's output), report the error and stop. Do not open a browser on an address that does not answer.
+
+## Step 4: Open it
+
+| System | Command |
+|---|---|
+| Windows (PowerShell) | `Start-Process "http://localhost:<port>/"` |
+| Windows (cmd) | `start "" "http://localhost:<port>/"` |
+| macOS | `open "http://localhost:<port>/"` |
+| Linux desktop | `xdg-open "http://localhost:<port>/"` |
+
+When there is no desktop to open a browser on (an SSH session, a container, a remote workspace), do not try: give the URL, and say that the port may need forwarding.
+
+## Step 5: Report
+
+- the URL;
+- how it was started, and how to stop it: `docker compose down`, `docker rm -f <container-name>`, or how to end the background command;
+- anything in the startup output the user should know.
+
+## What goes wrong
+
+- **The port is taken.** The start fails with "address already in use" or "port is already allocated". Find what holds it and tell the user; do not stop a process or container this skill did not start. For a single container, another host port is a fine answer.
+- **It was already running.** Then say so and open it; restart only if the source changed or the user asks.
+- **The page is HTTPS-only in the README.** A container started from the command line usually has no development certificate and serves HTTP only. Use the `http://` address.
+- **A container is "up" and serves nothing.** `docker ps` shows a started process, not a working app. Step 3 is the check that counts.

package/assets/skills/sdd-discuss/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: sdd-discuss
+description: >-
+  Turns an idea into an agreed specification, by conversation: asks for the
+  vision, reflects it back, reads the codebase, asks focused rounds of
+  questions until the goals, scope, users, definition of done, risks and
+  external systems are clear, then records the project brief, the numbered
+  requirements and the milestone context for the user to approve. Use at the
+  start of a project or of a new milestone, when the user wants to discuss or
+  change what is being built, or when sdd-wizard finds nothing planned yet.
+disabled: true
+---
+
+# Skill: Discuss
+
+The first phase of spec-driven development. Its product is agreement, on the record: what is being built, for whom, and what "done" means. Everything later is planned and checked against what this records. No code is written here.
+
+Part of the spec-driven set: `sdd-wizard` (where am I, what is next), `sdd-discuss`, `sdd-plan`, `sdd-execute`, `sdd-verify`, `sdd-quick`, `sdd-status`. Each works when the others are off; where this skill hands over to one that is not enabled, do that step directly by the rules given here.
+
+## The `sdd` tool
+
+The plan is kept in a database in the project (`.sdd/sdd.db`), and you reach it only through the **`sdd` tool**. The database is the truth: what is wanted, the milestones, their slices and tasks, what was proved, and which step is due.
+
+- **`sdd` with action `next`** answers with the one step that is due and everything that step needs. Call it when you start and whenever you are unsure. Do not work out the next step yourself, and do not rely on what was said earlier in a conversation.
+- Every other action records one thing and answers with the next step. An action out of turn is **refused**, with the reason and what to do instead. Do what it says; do not look for a way round it.
+- The markdown under `.sdd/` (`PROJECT.md`, `REQUIREMENTS.md`, `DECISIONS.md`, `KNOWLEDGE.md`, `STATE.md`, and a folder per milestone with its roadmap, plans and summaries) is **written by the tool** from the database, for people to read and review. Read it when it helps. **Never edit it**: an edit is overwritten, and the plan does not change.
+- The tool gives the ids: `M001` (milestone), `S01` (slice), `T01` (task), `R001` (requirement), `D001` (decision).
+- A **milestone** is a deliverable someone could ship. A **slice** is a vertical piece of it that can be demonstrated on its own. A **task** is one unit of work small enough to do, verify and describe in one sitting.
+- Only you, the lead, call `sdd`. An agent or a teammate given a task works on the code and reports; it does not record anything.
+
+If you do not have a tool called `sdd`, this skill cannot run. Say so: the tool is offered when a task starts with a spec-driven skill turned on, so the user starts a new task. Do not imitate the tool by writing the files yourself.
+
+## How to hold the conversation
+
+- **Reflect before asking.** Show that you understood before you ask for more.
+- **Investigate before asking.** Do not ask what the repository or the documentation can answer.
+- **Ask in small rounds:** one to three questions on one topic, with choices where the likely answers are few and your recommendation first. Use the question tool if you have one. Never a questionnaire.
+- **Use the user's words** in what you record. Later steps see only the record; a paraphrase loses what the user stressed.
+- **Do not shrink the vision.** Do not ask for "the minimum version" or talk the user down. What is large or risky is placed in a later milestone, not cut.
+- **A missing answer is not a yes.** The two approvals below cannot be skipped or assumed.
+
+## Stage 1: The vision
+
+Ask what they want to build, or what this milestone is for. Then reflect it back concretely:
+
+- what you understood, in a few sentences;
+- the main capabilities, as a list;
+- an honest size: roughly how many milestones, and roughly how many slices in the first.
+
+Have them confirm or correct it before going on.
+
+For a vision that is clearly several milestones, map them first: a name, one line of intent and the dependencies for each. Then discuss the first in depth; the others are kept one line each (`sdd` action `capture`) and are discussed when their turn comes.
+
+## Stage 2: Investigate
+
+Before the first question round, look:
+
+- **an existing project:** its README, manifest, layout, tests, the code this work will touch, and what earlier milestones recorded (`.sdd/DECISIONS.md` and `.sdd/KNOWLEDGE.md` above all);
+- **an unfamiliar library or service:** its documentation, not your memory of it;
+- **a new project:** what the user already has, and the usual shape of this kind of thing.
+
+With sub-agents available, a broad or unfamiliar codebase is a job for one: have it map the relevant area and report the files, the patterns in use and the constraints. It reads and reports only.
+
+## Stage 3: Question rounds
+
+Continue until all six are clear enough to explain to a stranger:
+
+1. **What** is being built: concrete behaviours, not qualities.
+2. **Why** it needs to exist.
+3. **Who** it is for, and how they will use it.
+4. **What "done" looks like:** what someone could see or do that proves it.
+5. **The biggest unknowns and risks:** technical, and otherwise.
+6. **What it touches outside itself:** services, APIs, data, credentials, other systems.
+
+Ask about what is out of scope as deliberately as about what is in. Do not ask "shall we wrap up?" after each round; go on until the six are covered or the user wants to stop. As soon as the first of these is confirmed, record the project with `sdd` action `set_project`, and call it again as more becomes clear: it replaces what was recorded, so an interrupted conversation loses nothing.
+
+## Stage 4: Depth check
+
+Print a structured summary of the six points, in the user's terms, and ask them to confirm that it is right and complete. **This is the first approval.** If they correct something, take it in and show the summary again.
+
+## Stage 5: Requirements
+
+Research briefly what such a thing normally needs that nobody mentioned: the behaviours users will expect, the standard pitfalls of the domain, what is commonly forgotten (errors, empty states, permissions, limits). Offer these as candidates; the user decides which are in.
+
+Then draft the requirements and show the whole table in the chat **before recording any**:
+
+| Requirement | Source | Status |
+|---|---|---|
+| one behaviour, stated so it can be proved | user / research / inferred | active / deferred / out of scope |
+
+Each requirement is one testable behaviour: a situation and an observable result. "Fast" is not a requirement; "the list of 10,000 rows appears within one second" is.
+
+**This is the second approval.** The user confirms, changes or adds.
+
+## Stage 6: Record
+
+Recheck the size estimate from Stage 1 against everything learned, and say so if it changed. Ask once, for the working agreements, whether they want a commit after each completed task. Then record, in this order, one `sdd` call each:
+
+1. **`set_project`** with `name`, `description` (what it is, who it is for, and what exists and works today), and `agreements` (commit after each task: yes or no; the test command; isolation, asked at the first slice; anything else the user asked for).
+2. **`add_requirement`** once per requirement: `title` (the behaviour, in one line), `description` (the situation and the observable result, and where it came from), and `status` when it is not active (`deferred`, `out_of_scope`). The tool numbers them.
+3. **`add_decision`** once per choice made in the discussion: `title`, `choice`, and `why` (including what was set aside).
+4. **`add_milestone`** with `title` and `context`. The context is the brief for everything that follows; write it with these headings, in the user's words:
+
+```markdown
+## Goal
+## Why
+## Who it is for
+## In scope
+## Out of scope
+## Done looks like         <- success criteria, each one observable
+## Unknowns and risks
+## External systems        <- including any credential that will be needed, and who provides it
+## Constraints
+## Open questions
+```
+
+5. **`approve`** with `what: "requirements"` — only because the user approved them in Stage 5. If they have not, do not call it; `next` will ask for it.
+
+Later milestones that were mapped in Stage 1 are kept with `capture`, one line each. Only one milestone is open at a time.
+
+Then say what was recorded and what `sdd` says is next, which is planning the milestone (`sdd-plan`). Commit `.sdd/` only if the working agreements say to commit.
+
+## Changing course later
+
+When the user comes back to change what is wanted mid-project, run the same conversation, shorter: reflect, ask only what the change leaves unclear, show the changed requirements, get approval. Then record it: `add_requirement` and `update_requirement` (a requirement no longer wanted becomes `deferred` or `out_of_scope`; it is not deleted), `update_milestone` for the context, and `add_decision` for the change itself. A new active requirement takes back the approval, so call `approve` again once the user agrees. Slices already completed are not changed. The slices still to be built are then revised by `sdd-plan`.
+
+## Credits
+
+Adapted from [Get Shit Done (GSD 2)](https://getshitdone.help/), source at [gsd-build/GSD-2](https://github.com/gsd-build/GSD-2). The milestone, slice and task hierarchy, the order of the phases, and keeping the plan in a database that says which step is due are GSD's. These skills use their own engine and their own folder (`.sdd/`), and are not compatible with a `.gsd/` folder.

package/assets/skills/sdd-execute/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: sdd-execute
+description: >-
+  Executes one planned task of spec-driven work: follows its task plan
+  exactly, builds the real thing and its tests, runs the plan's verification,
+  and records a summary with the evidence before the task counts as done. With
+  sub-agents enabled the task runs in a fresh agent and its changes are
+  checked before being adopted; with teammates enabled, independent slices can
+  run side by side. Use when sdd-wizard says a task is next, or the user asks
+  to execute, implement or resume the next task or a named one.
+disabled: true
+---
+
+# Skill: Execute
+
+Does one task from a slice plan, proves it, and records what happened. The task is the contract: this skill does not research again and does not redesign.
+
+Part of the spec-driven set: `sdd-wizard` (where am I, what is next), `sdd-discuss`, `sdd-plan`, `sdd-execute`, `sdd-verify`, `sdd-quick`, `sdd-status`. Each works when the others are off; where this skill hands over to one that is not enabled, do that step directly by the rules given here.
+
+## The `sdd` tool
+
+The plan is kept in a database in the project (`.sdd/sdd.db`), and you reach it only through the **`sdd` tool**. The database is the truth: what is wanted, the milestones, their slices and tasks, what was proved, and which step is due.
+
+- **`sdd` with action `next`** answers with the one step that is due and everything that step needs. Call it when you start and whenever you are unsure. Do not work out the next step yourself, and do not rely on what was said earlier in a conversation.
+- Every other action records one thing and answers with the next step. An action out of turn is **refused**, with the reason and what to do instead. Do what it says; do not look for a way round it.
+- The markdown under `.sdd/` (`PROJECT.md`, `REQUIREMENTS.md`, `DECISIONS.md`, `KNOWLEDGE.md`, `STATE.md`, and a folder per milestone with its roadmap, plans and summaries) is **written by the tool** from the database, for people to read and review. Read it when it helps. **Never edit it**: an edit is overwritten, and the plan does not change.
+- The tool gives the ids: `M001` (milestone), `S01` (slice), `T01` (task), `R001` (requirement), `D001` (decision).
+- A **milestone** is a deliverable someone could ship. A **slice** is a vertical piece of it that can be demonstrated on its own. A **task** is one unit of work small enough to do, verify and describe in one sitting.
+- Only you, the lead, call `sdd`. An agent or a teammate given a task works on the code and reports; it does not record anything.
+
+If you do not have a tool called `sdd`, this skill cannot run. Say so: the tool is offered when a task starts with a spec-driven skill turned on, so the user starts a new task. Do not imitate the tool by writing the files yourself.
+
+## Which task
+
+Call `sdd` with action `next`.
+
+- `execute_task`: the answer is the task: its steps, its files, its `Verify` command and what to expect from it. Call `sdd` action **`start_task`** before changing anything.
+- `resume_task`: the task was started and not finished. Read what is already changed in the workspace before creating anything, and continue it. Do not call `start_task` again.
+- anything else: this is not the step that is due. Say which step is, and which skill does it.
+
+Tasks are done in order, one at a time; the tool refuses to start one while another is in progress or an earlier one is not done.
+
+## What the executor is given
+
+Exactly this, and nothing from the conversation:
+
+- the task, in full, as `next` gave it;
+- the slice's goal, and the summaries of the tasks already done in this slice (`.sdd/milestones/M###/slices/S##/tasks/`);
+- `.sdd/DECISIONS.md` and `.sdd/KNOWLEDGE.md`;
+- the working agreements in `.sdd/PROJECT.md`.
+
+## The executor's rules
+
+1. **Read the inputs** the plan lists before changing anything.
+2. **Follow the plan.** Correcting a path, a name or a small factual slip in the plan is part of the job; say so in the summary. Changing the approach is not.
+3. **Build the real thing.** No stubs, no hard-coded success, no screen that renders invented data. If the plan says an endpoint authenticates, it authenticates.
+4. **Tests are part of the task,** written or updated with the code. Errors and edge cases get the same care as the normal path.
+5. **Stay inside the task.** Touch the files the task names. Something else that looks wrong is noted in the summary, not fixed.
+6. **Verify with the plan's commands,** and read the output. A command that could not run is not a pass.
+7. **When verification fails, debug deliberately:** one hypothesis, one change, run again. After three real attempts that did not fix it, stop and report, with what was tried.
+8. **A blocker is rare and specific:** a finding that makes the rest of the plan invalid. Say so plainly, with the evidence, and stop. A failing test or a hard bug is not a blocker.
+9. **Secrets:** never print, invent or commit one. If a credential is missing, stop and ask.
+10. Do not push, publish, open issues or change anything outside the project without the user's explicit yes.
+
+## Git isolation (optional)
+
+A slice can be built in its own git worktree, on its own branch, so the user's working copy stays exactly as it is until the slice is verified. It is optional: when it is not possible, say once why and carry on without it.
+
+**Whether to use it.** Read "Isolation" in the working agreements (`.sdd/PROJECT.md`). If it is not there, ask once, at the first task of the first slice (worktree, or none), and record the answer with `sdd` action `set_project`, giving the agreements again with the answer added. With "none", skip this section.
+
+**Whether it is possible.** Check with git before the slice's first task:
+
+```
+git rev-parse --is-inside-work-tree      # must print true
+git rev-parse --verify HEAD              # the repository must have a commit
+git status --porcelain                   # must list nothing outside .sdd/
+git worktree list                        # the git here must know worktrees
+```
+
+Uncommitted changes outside `.sdd/` would not be in the worktree, so the slice would be built without them: tell the user and let them commit or stash, or go on without isolation. If the project is not a git repository, or any check fails and cannot be put right by the user, go ahead without isolation and say so. Do not run `git init`, commit the user's changes or stash them yourself.
+
+**Create it** at the slice's first task:
+
+```
+git worktree add -b sdd/M001-S01 .sdd/worktrees/M001-S01 HEAD
+```
+
+and keep it out of the user's commits by adding the line `.sdd/worktrees/` to `.git/info/exclude` (not to their `.gitignore`). If the branch or the folder already exists, the slice was started before: use it, do not recreate it.
+
+**Work in it.**
+
+- Every product file of the slice is read and changed under `.sdd/worktrees/M001-S01/`, and every build, test and verification command runs from that folder. A task plan's paths are relative to it.
+- A fresh worktree has no installed dependencies and no ignored files (no `node_modules`, no virtual environment, no `.env`). Install from the lockfile before the first verification, and tell the user if the project needs a local file that is not in git.
+- **The plan is the one in the main checkout.** `sdd` always works on the project you were started in. The worktree may contain an older copy of `.sdd/`; never read it for the plan, and never write it.
+- After each task that passed its verification, commit in the worktree: the summary's first line as the message, and a trailer `SDD-Task: M001/S01/T01`. These commits are on the slice's branch and do not touch the user's branch, so they are made whatever the working agreements say about committing.
+- With a sub-agent, give it the worktree paths; its changes are adopted into the worktree, and the verification is run again there.
+- With teammates running slices side by side, each slice has its own worktree. That is what keeps them apart.
+
+The slice is merged back, and the worktree removed, when it is closed (`sdd-verify`). Never delete a worktree or its branch while it holds work that has not been merged, and never push.
+
+## Who executes
+
+**With sub-agents (you have `spawn_agent`) — preferred.** A task done in a fresh context is done against the plan and nothing else.
+
+**First check that you can take the agent's work back.** An agent works on its own copy, and its changes return as revisions that are adopted with `restore_file`. That tool exists only when Checkpoints or the change protocol is turned on. Look at your tools: if you have `spawn_agent` and do **not** have `restore_file`, do not start. Stop and tell the user:
+
+> Sub-agents are on, but Checkpoints are off, so I could not bring an agent's changes back into your project. Turn on Checkpoints (or the change protocol) in the settings and run this again. Or tell me to go ahead without agents, and I will do the tasks myself in this conversation.
+
+Go on without agents only after they say so; then add "Agents: not used (no checkpoints)" to the working agreements (`sdd` action `set_project`) so the question is not asked at every task.
+
+1. Spawn one agent. Its task is the task as `sdd` gave it, in full, and the rules above; its knowledge files are the task's files plus `.sdd/DECISIONS.md` and `.sdd/KNOWLEDGE.md`. Tell it not to call `sdd` and not to write under `.sdd/`. If the plan's verification is a command, give it as the agent's `check` (`command`, and `expect` when the output must show something), so "done" is tested and not claimed.
+2. Ask it to end its report with: files changed, each verification command with its exit code and what the output showed, deviations from the plan, known issues, decisions made, and whether it found a blocker.
+3. The agent worked on its own copy of the project. Its changed files come back as revisions. **Read them** (at least the diff of each against what the plan asked for), then adopt them into the workspace with `restore_file`.
+4. **Run the plan's verification again in the real workspace.** The agent's check passed on its copy; the task is done when it passes here.
+5. You record the task with `sdd`. An agent's files under `.sdd/` are not adopted.
+
+Tasks of one slice run one after another, each seeing the summaries before it. Only tasks that the plan marks as not depending on each other, and that write different files, may run as one batch.
+
+**With teammates as well (you have the `team_*` tools).** Use them for two things only:
+
+- **Independent slices side by side.** When the roadmap has two or more unchecked slices that do not depend on each other and are both planned, spawn one teammate per slice, put each slice's tasks on the board with `team_task` and their `dependsOn`, and run the slices with `team_run_task` in `async` mode. Each teammate does its slice's tasks in order. You adopt and verify each task's result as it is handed back, exactly as in steps 3 to 5, and you mark the board task complete yourself. Slices that touch the same files are not independent, whatever the roadmap says: run those one after the other.
+- **A reviewer for the slice.** One teammate, kept for the whole slice, that reads each adopted task against its plan and reports what does not match. It keeps what it learned from the earlier tasks. It reviews; it does not edit.
+
+Shut the teammates down when their slices are closed.
+
+**With neither.** Execute the task yourself, by the rules above. Work from the task as `sdd` gave it, not from what you remember of the planning.
+
+## Record it
+
+When the task's `Verify` command has passed **in the real workspace**, call `sdd` action **`complete_task`** with:
+
+- `summary`: one line saying what now exists (also the commit message, if committing), then what was built, the files changed, any deviation from the plan, and known issues;
+- `evidence`: the verification as it ran: the command, its exit code, and what its output showed. Paste the relevant output. Never write it from memory, and never for a command that did not run. The tool refuses a task without it.
+
+A task whose check did not pass is not completed. If it cannot be done as planned, call `sdd` action **`block_task`** with `reason`: what was found, and the evidence. The next step is then a replan (`sdd-plan`), not the next task.
+
+Also:
+
+- record real decisions with `add_decision`, and anything a later task would otherwise trip over with `add_knowledge`;
+- commit, if the working agreements say to, with the summary's first line as the message. Never commit secrets or build output.
+
+Report in a few lines: what was built, the evidence, anything that deviated, and the next step as `sdd` gave it.
+
+## Credits
+
+Adapted from [Get Shit Done (GSD 2)](https://getshitdone.help/), source at [gsd-build/GSD-2](https://github.com/gsd-build/GSD-2). The milestone, slice and task hierarchy, the order of the phases, and keeping the plan in a database that says which step is due are GSD's. These skills use their own engine and their own folder (`.sdd/`), and are not compatible with a `.gsd/` folder.

package/assets/skills/sdd-plan/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: sdd-plan
+description: >-
+  Plans spec-driven work at whichever level is next: turns an approved
+  milestone context into a roadmap of demoable slices ordered by risk, or
+  researches one slice and breaks it into small, fully specified tasks, each
+  with its files, steps and a verification command, then audits the plan.
+  Also replans a slice after a blocker and plans remediation slices after a
+  failed validation. Use after sdd-discuss, when sdd-wizard says a milestone
+  or slice needs planning, or when the user asks to plan, replan or break
+  down the work.
+disabled: true
+---
+
+# Skill: Plan
+
+Plans the work so that whoever executes it needs nothing but the plan. It works at two levels and does the one that is due: a **milestone** becomes a roadmap of slices; a **slice** becomes tasks. No product code is written here.
+
+Part of the spec-driven set: `sdd-wizard` (where am I, what is next), `sdd-discuss`, `sdd-plan`, `sdd-execute`, `sdd-verify`, `sdd-quick`, `sdd-status`. Each works when the others are off; where this skill hands over to one that is not enabled, do that step directly by the rules given here.
+
+## The `sdd` tool
+
+The plan is kept in a database in the project (`.sdd/sdd.db`), and you reach it only through the **`sdd` tool**. The database is the truth: what is wanted, the milestones, their slices and tasks, what was proved, and which step is due.
+
+- **`sdd` with action `next`** answers with the one step that is due and everything that step needs. Call it when you start and whenever you are unsure. Do not work out the next step yourself, and do not rely on what was said earlier in a conversation.
+- Every other action records one thing and answers with the next step. An action out of turn is **refused**, with the reason and what to do instead. Do what it says; do not look for a way round it.
+- The markdown under `.sdd/` (`PROJECT.md`, `REQUIREMENTS.md`, `DECISIONS.md`, `KNOWLEDGE.md`, `STATE.md`, and a folder per milestone with its roadmap, plans and summaries) is **written by the tool** from the database, for people to read and review. Read it when it helps. **Never edit it**: an edit is overwritten, and the plan does not change.
+- The tool gives the ids: `M001` (milestone), `S01` (slice), `T01` (task), `R001` (requirement), `D001` (decision).
+- A **milestone** is a deliverable someone could ship. A **slice** is a vertical piece of it that can be demonstrated on its own. A **task** is one unit of work small enough to do, verify and describe in one sitting.
+- Only you, the lead, call `sdd`. An agent or a teammate given a task works on the code and reports; it does not record anything.
+
+If you do not have a tool called `sdd`, this skill cannot run. Say so: the tool is offered when a task starts with a spec-driven skill turned on, so the user starts a new task. Do not imitate the tool by writing the files yourself.
+
+## Which plan is due
+
+Call `sdd` with action `next`:
+
+- `plan_milestone` → **Part A**.
+- `approve_roadmap` → show the roadmap and ask (the end of Part A).
+- `plan_slice` → **Part B**, for the slice it names. Slices added by a failed audit are planned the same way.
+- `replan_slice` → **Part C**.
+
+If `next` says `discuss_project`, `discuss_milestone` or `approve_requirements`, planning has nothing to stand on yet: say so and go to `sdd-discuss`.
+
+## Part A: The roadmap
+
+Read the milestone's context and the requirements (in the answer of `next`, and in `.sdd/REQUIREMENTS.md`, `.sdd/DECISIONS.md`, `.sdd/KNOWLEDGE.md`), the summaries of earlier milestones, and the code this milestone will touch. Research to the depth the uncertainty deserves: a small feature in a known codebase needs a look at the relevant files; new technology or an unfamiliar system needs the documentation read and the alternatives weighed. With sub-agents, give a broad survey to one and have it report the files, the patterns and the natural seams.
+
+Then cut the milestone into slices, by these rules:
+
+- **Vertical.** Every slice delivers something a person could see working, end to end through whatever layers it needs. Not "the database layer", not "the API": a capability.
+- **Risk first.** The earliest slices prove the riskiest assumptions, through real working features and not throwaway spikes.
+- **Honest count.** As many slices as the milestone's ambition needs. One for a simple feature; several for something that promises several capabilities.
+- **Every active requirement of this milestone lands somewhere:** owned by a slice, or explicitly deferred, blocked with a reason, or moved out of scope. A requirement that silently belongs to nothing is a planning failure.
+- **Dependencies are stated**, and nothing depends on a later slice.
+
+Record it with `sdd` action **`plan_milestone`**, `slices` in order, each with:
+
+- `title`;
+- `goal`: what is true when the slice is done, the risk it settles (high, medium or low), and what it produces that a later slice consumes;
+- `demo`: what a person can see or do when it is done;
+- `depends`: the earlier slices it needs, e.g. `["S01"]`;
+- `requirements`: the requirement ids it delivers, e.g. `["R001", "R004"]`.
+
+The tool refuses a roadmap in which an active requirement belongs to no slice, or a slice depends on a later one. Fix the roadmap, or with the user's agreement defer the requirement (`update_requirement`), and call again.
+
+Then **show the roadmap to the user** as a table (slice, title, risk, depends on, what can be demonstrated) and ask whether to build it this way. To change it, call `plan_milestone` again: it replaces the roadmap as long as it is not approved. When the user agrees, call **`approve`** with `what: "roadmap"`. Never before.
+
+Record the structural choices (the order and why, technology picked, scope left out) with `add_decision`. If the milestone needs credentials or accounts the user must provide, list them now, with where each is obtained, so they are ready before execution; never invent or write a secret value.
+
+A roadmap with a single slice goes straight on to Part B in the same sitting, once it is approved.
+
+## Part B: One slice
+
+Slices are planned one at a time, when they are due, so that each plan can use what the earlier slices found. The tool refuses to plan a slice before its turn.
+
+### B1. Research
+
+`next` gives the slice's goal, its demo, and the summaries of the slices already done. Read those, the requirements it owns, and then the code. Match the depth to the work:
+
+- **light:** well-understood work on patterns the codebase already has. Fifteen lines saying "this is straightforward, follow the pattern in `<file>`" is the right research.
+- **targeted:** known technology that is new to this codebase.
+- **deep:** new technology, an unfamiliar API, a risky integration, unclear scope.
+
+Write the research as text, for a planner who has no memory of the exploration: what exists (the specific files and what is in them), the patterns to follow, the seams where the work divides into tasks, what to build or prove first, the pitfalls, and the commands that verify the slice. It goes into `plan_slice` as `research`.
+
+With sub-agents, research is one agent's job: it reads and reports; you record its report.
+
+### B2. Tasks
+
+Break the slice into tasks. Each task is the **whole contract** for whoever executes it: they are given that task and a line about the slice's goal, and nothing else. So everything needed is in it.
+
+- **Size:** two to five steps and three to eight files. Ten steps or twelve files means it is two tasks.
+- **Order:** each task's output unblocks the next. If the slice has tests, the first task creates them, failing.
+- **Paths are exact,** in backticks. "The auth module" is not a path.
+- **Done is checkable:** a command that exits 0, or an observable result. Not "works correctly".
+- **Real, not stubbed:** a task that says "create a login endpoint" means one that authenticates against a real store. Mocks belong in tests.
+
+Each task has:
+
+- `title`;
+- `steps`: the numbered steps; then **Must have** (the behaviours that have to hold, including the error cases), **Done when** (observable and checkable) and **Out of scope** (what this task must not touch);
+- `files`: the files to read first and the files to create or change, exact paths;
+- `verify`: the **one command** whose output proves the task. Required: the tool refuses a task without it;
+- `expect`: what that output shows when the task is done (exit 0, "12 passed").
+
+### B3. Audit the plan
+
+Before recording it, check, and fix the plan if a check fails:
+
+1. **If every task were done exactly as written, would the slice goal be true?**
+2. Every requirement the slice owns has a task that advances it, and a verification that would prove it.
+3. The order respects the dependencies; no task reads a file a later task creates.
+4. Every task is within the size limits and has a real verification.
+5. Nothing reaches outside the slice.
+
+Then review the plan for what plans usually miss. With sub-agents, run these as one batch of reviewers, each given the slice plan and one question; otherwise answer them yourself. Each answer is **pass**, **flag** (a concern, with what to do) or **not applicable**:
+
+- **Security:** does the slice touch authentication, permissions, input from outside, secrets or personal data, and does the plan handle it?
+- **Failure modes:** what happens when each external call, file or input fails? Is that in a task's "Must have"?
+- **Load:** is there a volume or timing the plan ignores?
+- **Negative tests:** do the tests cover what must be refused, not only what must work?
+
+A flag does not block. Write the flagged handling into the `steps` of the task it belongs to.
+
+Then record the plan with `sdd` action **`plan_slice`**: `research` and `tasks`, in order. Record any structural decision with `add_decision`.
+
+## Part C: Replan after a blocker
+
+A blocker is a finding that makes the remaining plan invalid: the API does not do what was assumed, a capability is missing, the architecture cannot take it. A bug or a failing test is not a blocker; that is ordinary work.
+
+`next` gives the blocker as the executor reported it. Read the slice's state. Then call `sdd` action **`replan_slice`** with `reason` (what was found, what changes, why) and the new `tasks`. Tasks already done are kept as they are; the tool replaces only the ones that are not, and numbers the new ones after them.
+
+If `next` says the slice was already replanned once, it needs the user: put the blocker to them before planning again. If the finding changes what the slice can deliver, or touches a requirement, stop and tell the user before going on.
+
+Then say what was planned and what `sdd` says the next step is. Commit `.sdd/` only if the working agreements say to commit.
+
+## Credits
+
+Adapted from [Get Shit Done (GSD 2)](https://getshitdone.help/), source at [gsd-build/GSD-2](https://github.com/gsd-build/GSD-2). The milestone, slice and task hierarchy, the order of the phases, and keeping the plan in a database that says which step is due are GSD's. These skills use their own engine and their own folder (`.sdd/`), and are not compatible with a `.gsd/` folder.

package/assets/skills/sdd-quick/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: sdd-quick
+description: >-
+  Does a small, self-contained change without the planning ceremony of
+  spec-driven development: reads the relevant code, makes the change properly
+  with its tests and error cases, verifies it, and leaves a short written
+  record. Does not touch the roadmap. Use for a targeted bug fix, a small
+  tweak or a one-off change in a project that uses spec-driven development,
+  or when the user asks for a quick task.
+disabled: true
+---
+
+# Skill: Quick Task
+
+For work that does not deserve a milestone: a targeted fix, a small change, a short exploration. No discussion rounds, no roadmap, no slice. The standard of the work is the same as for any planned task.
+
+Part of the spec-driven set: `sdd-wizard` (where am I, what is next), `sdd-discuss`, `sdd-plan`, `sdd-execute`, `sdd-verify`, `sdd-quick`, `sdd-status`. Each works when the others are off; where this skill hands over to one that is not enabled, do that step directly by the rules given here.
+
+## Is it quick?
+
+Yes, when it is one clear change that can be done and verified in one sitting and touches a handful of files.
+
+No, when it needs a design decision, changes what the product does for its users, spans several parts of the system, or the user cannot say what "done" is. Then say so and suggest `sdd-discuss`; do not grow a quick task into an unplanned feature.
+
+## Do it
+
+1. **Restate the task** in one line, and what will show it is done. Ask only if that is genuinely unclear.
+2. **Read before changing:** the code involved, and if the project has a `.sdd/` folder, its `DECISIONS.md` and `KNOWLEDGE.md`, so the change follows what was already decided.
+3. **Make the real change.** No placeholders. Error cases and edge cases get the same care as the normal path. Add or update a test when the code has tests.
+4. **Stay on the task.** Something else that looks wrong is mentioned, not fixed.
+5. **Verify:** run the relevant tests and whatever shows the change works. When a check fails, one hypothesis and one change at a time; after three attempts that did not fix it, stop and report.
+6. **Record it** with the `sdd` tool, action **`quick`**: `title` (what changed, in one line) and `summary` (why, the files changed, the verification with its command and what it showed, and what was noticed but not changed). The tool numbers it (`Q001`) and writes `.sdd/quick/Q001-SUMMARY.md`. In a project where spec-driven development has not been started, or without the `sdd` tool, give the same summary in the reply instead. Do not write files under `.sdd/` yourself.
+7. If the change taught something a later task would trip over, record it with `sdd` action `add_knowledge`. If it contradicts a recorded decision, stop and ask before making it.
+8. Commit only if the project's working agreements (in `.sdd/PROJECT.md`) or the user say to: one commit, with the summary's first line as its message. Never commit secrets or build output, and never push without an explicit yes.
+
+The roadmap, the requirements and the slice plans are not touched by a quick task; `quick` records it and changes nothing else. If the change does affect a requirement or a planned slice, it was not quick: say so.
+
+## Credits
+
+Adapted from [Get Shit Done (GSD 2)](https://getshitdone.help/), source at [gsd-build/GSD-2](https://github.com/gsd-build/GSD-2). The milestone, slice and task hierarchy, the order of the phases, and keeping the plan in a database that says which step is due are GSD's. These skills use their own engine and their own folder (`.sdd/`), and are not compatible with a `.gsd/` folder.