From d4937fd0f561fb06bcaa0a91f214076003bbe89c Mon Sep 17 00:00:00 2001 From: Tom Kaczocha Date: Fri, 14 Aug 2026 11:24:07 +1000 Subject: [PATCH] docs: product noun Issue; freeze wire at ur.*/UR-NNN Align agent docs with do-work.io UI (Issue / issues tables) without renaming MCP capabilities, slugs, port ops, or markdown user-requests/ paths. Document Linear Issue (REQ) vs do-work Issue disambiguation. --- CHANGELOG.md | 7 ++++++ README.md | 4 ++-- SKILL.md | 41 +++++++++++++++++++---------------- agents/capture.md | 2 +- agents/close.md | 4 ++-- agents/ideate.md | 10 ++++----- agents/intake.md | 14 ++++++------ agents/run-worker.md | 4 ++-- agents/start.md | 2 +- agents/tracker/do-work-io.md | 40 +++++++++++++++++++++++----------- agents/tracker/port.md | 42 ++++++++++++++++++------------------ docs/concepts.md | 13 ++++++----- references/concepts.md | 8 +++---- references/field-lessons.md | 28 ++++++++++++++++++++++++ references/linear-paths.md | 10 ++++----- references/tracker.md | 10 ++++----- 16 files changed, 147 insertions(+), 92 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 813b9af..4ea318d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ## Unreleased +**Product noun: Issue (wire still `ur.*` / `UR-NNN`)** + +**Changed** +- Agent docs use **Issue** as the product noun for the top-level brief container (aligned with do-work.io UI / `issues` table). **Wire frozen:** MCP/capabilities stay `ur.*` / `ur_*`, param `ur`, slug `UR-NNN`, port ops `create_ur` / `read_ur` / … — do **not** invent `issue.create` or `ISSUE-NNN` until a deliberate capability cutover. +- `agents/tracker/do-work-io.md`: hierarchy documents `issues` / `issue_artifacts`; explicit “Product naming vs wire” table. +- `SKILL.md`, `docs/concepts.md`, `references/concepts.md`, `references/tracker.md`, `agents/tracker/port.md`, intake/ideate/run-worker, Linear hierarchy notes: Issue vs Linear Issue (REQ) disambiguation; markdown paths still `.do-work/user-requests/`. + **MCP wire names (Grok-safe; `.` → `_`)** **Changed** diff --git a/README.md b/README.md index 27f10f0..a3737ee 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ Task-based guides for installing and running `/do-work` (not contributor interna |-------|----------| | [docs/README.md](docs/README.md) | Docs index | | [docs/getting-started.md](docs/getting-started.md) | Install → first start → first go | -| [docs/concepts.md](docs/concepts.md) | UR, REQ, gates, evidence | +| [docs/concepts.md](docs/concepts.md) | Issue (slug `UR-NNN`), REQ, gates, evidence | | [docs/commands.md](docs/commands.md) | Command and flag reference | | [docs/troubleshooting.md](docs/troubleshooting.md) | Common failure symptoms | | [docs/HOW-IT-WORKS.md](docs/HOW-IT-WORKS.md) | Phase-by-phase deep dive | @@ -72,7 +72,7 @@ Override the hub directory with `AGENTS_SKILLS_HUB` (same as `install.sh`). Wire This records your brief, runs a creative review (ideate), and decomposes it into REQ files — all in one shot. -Add `--no-ideate` to skip the creative review. Add `--no-layers` to skip layer-coverage checks for this UR (records the choice in UR state for audit). +Add `--no-ideate` to skip the creative review. Add `--no-layers` to skip layer-coverage checks for this Issue (records the choice in Issue state for audit). Ideate now ends with an interactive gate — after surfacing gaps, it asks whether you want to be **grilled** with one-at-a-time questions, **continue** to capture as-is, or **stop** to revise the brief yourself. diff --git a/SKILL.md b/SKILL.md index ede2f6a..3369635 100644 --- a/SKILL.md +++ b/SKILL.md @@ -2,13 +2,14 @@ name: do-work description: > Autonomous project-management loop: natural-language briefs → traceable work - items (URs/REQs) → isolated TDD workers with one git commit per task. Default - store is local markdown under .do-work/; optional Linear, sqlite, or - do-work-io as sole backend via tracker.backend (no dual-write, hard-stop if - the active backend is unusable). Differentiator: multi-agent runs with footprint-aware claims, - worktree isolation, and verify/review/archive gates — not a generic todo list. + items (Issues/REQs; Issue slug still UR-NNN, wire ur.*) → isolated TDD workers + with one git commit per task. Default store is local markdown under .do-work/; + optional Linear, sqlite, or do-work-io as sole backend via tracker.backend + (no dual-write, hard-stop if the active backend is unusable). Differentiator: + multi-agent runs with footprint-aware claims, worktree isolation, and + verify/review/archive gates — not a generic todo list. Triggers on: "do-work", "intake", "capture", "verify", "run the loop", - "backlog", "user request", "REQ-", "UR-", "question", "audit", + "backlog", "user request", "Issue", "REQ-", "UR-", "question", "audit", "linear backlog", "tracker.backend", "migrate to Linear", "sqlite board". --- @@ -25,7 +26,7 @@ Most days you only need these: | Command | What it does | |---------|-------------| | `/do-work start [brief]` | Record a brief and build the REQ backlog (ideate on by default; auto-installs). | -| `/do-work go [UR-NNN]` | Verify coverage, then audit + run when confidence ≥ threshold (default 90%). | +| `/do-work go [UR-NNN]` | Verify coverage, then audit + run when confidence ≥ threshold (default 90%). Issue slug is still `UR-NNN`. | | `/do-work status [UR-NNN]` | Live situation room: in-flight, backlog, recent done, coverage. | | `/do-work board` | Regenerate static HTML board from work.db (sqlite only). | | `/do-work` | Help + suggested next steps for this project. | @@ -38,27 +39,27 @@ Flags for start/go (`--no-ideate`, `--force`, `--auto-fix`, …) are in the full |---------|-------------| | `/do-work start [brief]` | Records brief + decomposes into REQs in one shot. Includes ideate by default. Auto-installs if needed. | | `/do-work start [brief] --no-ideate` | Same as start, but skips the creativity review before decomposition. | -| `/do-work start [brief] --no-layers` | Same as start, but skips layer-coverage checks for this UR (records `layers_in_scope: []`). | +| `/do-work start [brief] --no-layers` | Same as start, but skips layer-coverage checks for this Issue (records `layers_in_scope: []`). | | `/do-work go [UR-NNN]` | Verifies coverage, auto-runs if >= 90% confidence. | | `/do-work go [UR-NNN] --force` | Verifies + runs regardless of confidence score. | | `/do-work go [UR-NNN] --auto-fix` | Verifies, auto-fixes gaps, then runs if >= 90%. | -| `/do-work go [UR-NNN] --no-layers` | Verify + run, skipping layer-coverage checks for this UR. | +| `/do-work go [UR-NNN] --no-layers` | Verify + run, skipping layer-coverage checks for this Issue. | | `/do-work install` | Creates `.do-work/` structure in current project. | | `/do-work upgrade` | Brings the project's .do-work/ state into conformance with the current skill — runs the manifest's detectors and applies fixes (interactive confirmation on destructive rows). Idempotent. | -| `/do-work intake [brief]` | Records brief verbatim as next UR file. | -| `/do-work capture [UR-NNN]` | Decomposes a UR brief into REQ files in the backlog. | +| `/do-work intake [brief]` | Records brief verbatim as next Issue (slug `UR-NNN`). | +| `/do-work capture [UR-NNN]` | Decomposes an Issue brief into REQ files in the backlog. | | `/do-work question [UR-NNN]` | Grills you about your brief — extracts assumptions, gaps, constraints. | | `/do-work audit [UR-NNN]` | Interrogates REQ quality — auto-fixes soft spots, reports changes. | | `/do-work ideate [UR-NNN]` | Surfaces assumptions, risks, and connections in a brief. | | `/do-work verify [UR-NNN]` | Scores REQ coverage against brief (0-100%), lists gaps. | | `/do-work verify [UR-NNN] --auto-fix` | Verify + auto-create missing REQs. | -| `/do-work run [UR-NNN]` | Executes backlog: TDD loop, evidence validation, post-build review gate, archive/ledger. Optional UR-NNN scopes the run to that UR's REQs only. | +| `/do-work run [UR-NNN]` | Executes backlog: TDD loop, evidence validation, post-build review gate, archive/ledger. Optional `UR-NNN` scopes the run to that Issue's REQs only. | | `/do-work run [UR-NNN] --parallel N` | Single-session parallel mode: one terminal dispatches up to N concurrent workers (default 1 = serial, capped at 10), serializing merge/archive through a queue. Defaults from `parallel.max_workers`. | | `/do-work run [UR-NNN] --budget ` | Caps cumulative estimated model spend for the run; overrides `cost.budget` for this invocation. When estimated spend reaches the budget, the loop finishes the in-flight REQ's integration then stops at the next REQ boundary with a budget-stop report. Empty budget = unlimited (default). | | `/do-work review` | Internal post-build gate used by run after worker evidence validation and before archive completion; not directly invocable — see agents/review.md. | | `/do-work status [UR-NNN]` | Renders live situation room: REQs, claimers, heartbeats, deadlock warnings, and coverage rollup. Optional UR-NNN scopes the report. | | `/do-work board` | Regenerate static HTML board from work.db (sqlite only). | -| `/do-work close UR-NNN` | Validates the integrated result of a UR against its verbatim brief — walks every path-unit's entry point to its terminal state in the merged app and writes a closure report. | +| `/do-work close UR-NNN` | Validates the integrated result of an Issue against its verbatim brief — walks every path-unit's entry point to its terminal state in the merged app and writes a closure report. | | `/do-work retro` | Mines the run ledger and feedback fingerprints to produce a human report and regenerate `.do-work/state/calibration.md` — advisory capture guidance derived from historical patterns. | | `/do-work unblock REQ-NNN` | Forces a stuck REQ out of working/ back to the backlog — strips claim stamp, resets status. | | `/do-work resume REQ-NNN` | Re-dispatches a fresh worker for a stopped REQ — preserves claim, refreshes heartbeat. | @@ -75,7 +76,7 @@ Detailed instructions for each phase live in separate files. Read the referenced - [agents/start.md](agents/start.md) — Orchestrator: intake + ideate + capture - [agents/go.md](agents/go.md) — Orchestrator: verify + conditional run -- [agents/intake.md](agents/intake.md) — Records brief verbatim as next UR file +- [agents/intake.md](agents/intake.md) — Records brief verbatim as next Issue (`UR-NNN`) - [agents/upgrade.md](agents/upgrade.md) — Brings project state into conformance with the current skill - [agents/question.md](agents/question.md) — Interactive brief questioning - [agents/audit.md](agents/audit.md) — Autonomous REQ quality audit @@ -87,7 +88,7 @@ Detailed instructions for each phase live in separate files. Read the referenced - [agents/review.md](agents/review.md) — Post-build gate: reviews scope, acceptance evidence, tests, secrets, docs, and regression risk before archive - [agents/status.md](agents/status.md) — Read-only situation room: REQs, claimers, heartbeats, deadlock warnings, coverage rollup - [agents/board.md](agents/board.md) — Static HTML board snapshot from work.db (`/do-work board`, sqlite only) -- [agents/close.md](agents/close.md) — Validates the integrated result of a UR against its verbatim brief; walks path-unit entry points in the merged app; writes `UR-NNN/closure.md` +- [agents/close.md](agents/close.md) — Validates the integrated result of an Issue against its verbatim brief; walks path-unit entry points in the merged app; writes `UR-NNN/closure.md` - [agents/unblock.md](agents/unblock.md) — Force a stuck in-flight REQ back to the backlog - [agents/resume.md](agents/resume.md) — Re-dispatch a fresh worker for a stopped REQ - [agents/log.md](agents/log.md) — Generates build-in-public draft posts @@ -129,13 +130,15 @@ Full multi-backend deep dive: [references/tracker.md](references/tracker.md). Canonical contract: `agents/tracker/port.md` hard-stop matrix + Load Config steps 6–7c / 8 in `agents/config.md`. -**No dual-write.** One active backend owns work-item truth (markdown, linear, sqlite, **or** do-work-io). Agents must not mirror URs/REQs across stores, and must not fall back when the active backend fails (hard-stop instead). Switching to sqlite is **greenfield** (empty DB; no history migration in v1). `/do-work board` is **sqlite-only** (static HTML snapshot). After idle markdown→Linear migration (`/do-work upgrade migrate`), historical `.do-work/user-requests/` and `archive/` trees remain on disk as **read-only history** — work-item ops ignore them. **Refuse** `migrate_markdown_to_linear` when already on `sqlite` or `do-work-io`. +**No dual-write.** One active backend owns work-item truth (markdown, linear, sqlite, **or** do-work-io). Agents must not mirror Issues/REQs across stores, and must not fall back when the active backend fails (hard-stop instead). Switching to sqlite is **greenfield** (empty DB; no history migration in v1). `/do-work board` is **sqlite-only** (static HTML snapshot). After idle markdown→Linear migration (`/do-work upgrade migrate`), historical `.do-work/user-requests/` and `archive/` trees remain on disk as **read-only history** — work-item ops ignore them. **Refuse** `migrate_markdown_to_linear` when already on `sqlite` or `do-work-io`. -**Linear hierarchy:** **UR = Project Milestone** on a **shared product Project** per local product (`tracker.linear.product_project` — name or UUID; **default empty**). Resolve: explicit `product_project` → `project.name` → git-root basename; `ensure_product_container` create-if-missing + **always persist UUID**. Never invent skill name `do-work` for empty config (example name for this skill repo only). REQs = Issues with that milestone. Not Initiatives (MCP has no Initiative create tools). +**Product noun vs wire:** top-level brief container is an **Issue** (UI + agent prose). Agent id / slug remains **`UR-NNN`**; do-work-io MCP stays **`ur.*`** / param **`ur`** until a deliberate capability cutover. Markdown folders stay `.do-work/user-requests/UR-NNN/`. On Linear, **do-work Issue (`UR-NNN`) ≠ Linear Issue** (Linear Issue = REQ). -**Linear commit / branch** (when `backend: linear`): subject uses Linear issue id only (`feat(ENG-123): …`); footer `Issue:` / `UR:` / `Output:`; branch/worktree `req/` (dir hard-defaults lowercase). Markdown backend still uses `feat(REQ-NNN): …` with `REQ:` / `UR:` archive paths — see [references/concepts.md](references/concepts.md#commit-convention). +**Linear hierarchy:** **do-work Issue (`UR-NNN`) = Project Milestone** on a **shared product Project** per local product (`tracker.linear.product_project` — name or UUID; **default empty**). Resolve: explicit `product_project` → `project.name` → git-root basename; `ensure_product_container` create-if-missing + **always persist UUID**. Never invent skill name `do-work` for empty config (example name for this skill repo only). **REQs = Linear Issues** with that milestone. Not Initiatives (MCP has no Initiative create tools). -**Operator warning (Linear claims):** human remains Issue assignee; agents claim via workflow state + claim-protocol comment (``). Do not clear/edit/delete agent claim comments in the Linear UI while a run is live. Recover with `/do-work status`, then `resume` or `unblock`. +**Linear commit / branch** (when `backend: linear`): subject uses Linear issue id only (`feat(ENG-123): …`); footer `Issue:` / `UR:` / `Output:` (`UR:` = parent do-work Issue slug); branch/worktree `req/` (dir hard-defaults lowercase). Markdown backend still uses `feat(REQ-NNN): …` with `REQ:` / `UR:` archive paths — see [references/concepts.md](references/concepts.md#commit-convention). + +**Operator warning (Linear claims):** human remains Linear Issue assignee; agents claim via workflow state + claim-protocol comment (``). Do not clear/edit/delete agent claim comments in the Linear UI while a run is live. Recover with `/do-work status`, then `resume` or `unblock`. Markdown remains the default. Operator setup: [docs/troubleshooting.md](docs/troubleshooting.md) § Linear tracker backend; [docs/HOW-IT-WORKS.md](docs/HOW-IT-WORKS.md) § Multi-tracker; [docs/getting-started.md](docs/getting-started.md). diff --git a/agents/capture.md b/agents/capture.md index 16b37ab..0e10e32 100644 --- a/agents/capture.md +++ b/agents/capture.md @@ -17,7 +17,7 @@ The following steps require model judgment that cannot be reduced to a rule. Eac ## When Invoked -You will be given a UR reference: +You will be given an Issue reference (slug `UR-NNN`): | Backend | Invocation | |---------|------------| diff --git a/agents/close.md b/agents/close.md index 9f0f366..809fdd2 100644 --- a/agents/close.md +++ b/agents/close.md @@ -1,8 +1,8 @@ # Close Agent -You are the Close agent in the Do Work system. Your job is to validate the **integrated** result of a UR against its verbatim brief — walking every path-unit's entry point to its terminal state in the merged app — and to write a per-path-unit closure report. +You are the Close agent in the Do Work system. Your job is to validate the **integrated** result of an **Issue** (slug `UR-NNN`) against its verbatim brief — walking every path-unit's entry point to its terminal state in the merged app — and to write a per-path-unit closure report. -You are dispatched **cold**: a fresh `Agent` subagent with no pipeline context. You are handed only the verbatim brief, the UR's archived path-unit REQs, and the project root + config. You did not run the loop, you did not see any worker report, verify/audit/review output, run ledger, or orchestrator conversation — and you must not read them. Per-REQ `**Closure proof:**` is exactly the optimism you exist to re-check independently; you never read it. +You are dispatched **cold**: a fresh `Agent` subagent with no pipeline context. You are handed only the verbatim brief, the Issue's archived path-unit REQs, and the project root + config. You did not run the loop, you did not see any worker report, verify/audit/review output, run ledger, or orchestrator conversation — and you must not read them. Per-REQ `**Closure proof:**` is exactly the optimism you exist to re-check independently; you never read it. You observe and report. You do **not** fix gaps, edit source, re-run the loop, or reopen REQs. Your only durable write is the closure report via the active tracker backend (`closure.md` under markdown; **`write_close_report`** under Linear — design §10). diff --git a/agents/ideate.md b/agents/ideate.md index 9b2ae47..3ef3e52 100644 --- a/agents/ideate.md +++ b/agents/ideate.md @@ -1,6 +1,6 @@ # Ideate Agent -You are the Ideate agent in the Do Work system. Your job is to think critically about a user request brief before it gets decomposed into tasks — surfacing assumptions, gaps, connections, and risks the user may not have considered. +You are the Ideate agent in the Do Work system. Your job is to think critically about an Issue brief (slug `UR-NNN`) before it gets decomposed into tasks — surfacing assumptions, gaps, connections, and risks the user may not have considered. You are powered by the Creativity Engine's three most relevant modes: Explorer, Challenger, and Connector. @@ -8,13 +8,13 @@ You are powered by the Creativity Engine's three most relevant modes: Explorer, ## When Invoked -You will be given a UR reference: +You will be given an Issue reference (slug still `UR-NNN`): | Backend | Invocation | |---------|------------| -| **markdown** | Path to a user-request folder, e.g. `{project}/.do-work/user-requests/UR-001/` | -| **linear** | UR slug (e.g. `UR-001`) and/or Linear **UR Project Milestone** id — **not** a required local folder | -| **do-work-io** | UR slug (e.g. `UR-001`) — **not** a required local folder | +| **markdown** | Path to an Issue folder, e.g. `{project}/.do-work/user-requests/UR-001/` | +| **linear** | Issue slug (e.g. `UR-001`) and/or Linear **Issue Project Milestone** id — **not** a required local folder | +| **do-work-io** | Issue slug (e.g. `UR-001`) — **not** a required local folder | You may also be invoked by the Start agent as part of the default pipeline (ideate runs unless `--no-ideate` is passed). diff --git a/agents/intake.md b/agents/intake.md index b606173..da8b95e 100644 --- a/agents/intake.md +++ b/agents/intake.md @@ -1,6 +1,6 @@ # Intake Agent -You are the Intake agent in the Do Work system. Your job is to receive a natural-language feature description or request and record it verbatim as the next user request file. Nothing else. +You are the Intake agent in the Do Work system. Your job is to receive a natural-language feature description or request and record it verbatim as the next **Issue** (slug `UR-NNN`). Nothing else. --- @@ -20,7 +20,7 @@ Read and follow the **Load Config** section of [config.md](config.md). ### 0a. Tracker load path -Work-item storage (URs, REQs, decisions, verify/close reports, run notes) goes **only** through named tracker port ops after config is loaded: +Work-item storage (Issues, REQs, decisions, verify/close reports, run notes) goes **only** through named tracker port ops after config is loaded: 1. Resolve effective `tracker.backend` (missing/empty/whitespace → `markdown`). 2. Read `agents/tracker/port.md` (shared op catalog + rules). @@ -172,7 +172,7 @@ received: YYYY-MM-DD status: intake --- -# UR-NNN: User Request +# UR-NNN: Issue ## Request @@ -187,20 +187,20 @@ After writing input.md, verify the file was recorded correctly: 2. Confirm the file begins with `---` and parses as a YAML frontmatter block 3. Confirm `status: intake` appears in the frontmatter 4. Confirm `received:` matches today's date -5. Confirm `ur:` matches the UR number you assigned +5. Confirm `ur:` matches the Issue slug you assigned 6. Confirm the `## Request` section in the body contains the user's original message (not a summary or paraphrase) If any check fails, fix the file before proceeding. This is the intake agent's equivalent of TDD's verify-green step — confirm the output matches the spec before committing. -### 5. Commit the UR +### 5. Commit the Issue -Stage and commit the new UR directory so it is tracked in git from the moment it's recorded. +Stage and commit the new Issue directory so it is tracked in git from the moment it's recorded. If the project is not a git repo, skip this step silently. ```bash git add {project}/.do-work/user-requests/UR-NNN/ -git commit -m "chore(UR-NNN): record user request" +git commit -m "chore(UR-NNN): record Issue" ``` ### 6. Report and prompt diff --git a/agents/run-worker.md b/agents/run-worker.md index cc3f9f3..062c497 100644 --- a/agents/run-worker.md +++ b/agents/run-worker.md @@ -21,8 +21,8 @@ The following steps require model judgment that cannot be reduced to a rule. Eac The orchestrator dispatches you with these named inputs: 1. **REQ file path** — absolute path to the REQ markdown file (already moved to `working/` by the orchestrator) -2. **UR input.md path** — absolute path to the originating user request brief -3. **Prior-REQ archived paths** — list of absolute paths to previously archived REQs from the same UR (may be empty) +2. **UR input.md path** — absolute path to the originating Issue brief (slug `UR-NNN`) +3. **Prior-REQ archived paths** — list of absolute paths to previously archived REQs from the same Issue (may be empty) 4. **Context pack path** — absolute path to `.do-work/state/context-pack.md`, a ~200-line orchestrator-generated map of the project (architecture, directory roles, key services, naming & test conventions, how to run the suite). Read it in Step 2. 5. **Skill root** — the absolute `$SKILL_ROOT` the orchestrator resolved once in **Load Config step 8** (`agents/config.md`: walk-up from loaded instruction file with `lib/` + (`SKILL.md` or `agents/`) markers, or inherit of a valid pre-set `$SKILL_ROOT`; hard-stop if unknown) and substituted into these instructions. It is the skill install root (the directory containing `lib/` and skill markers). Wherever these instructions write `{skill-root}/lib/...`, that means this passed-in value — substitute it. A worker `cd`'d into a consumer project's worktree has no local `lib/`; this is how your heartbeat / feedback calls resolve. Do **not** invent a second resolve recipe (no env/hub/CWD fallback). If the orchestrator omitted Skill root or left `{skill-root}` unsubstituted and you cannot determine the path, hard-stop per Load Config step 8 (inherit only when the value still satisfies markers; otherwise walk-up from the loaded instruction file). diff --git a/agents/start.md b/agents/start.md index 06640d2..facd655 100644 --- a/agents/start.md +++ b/agents/start.md @@ -63,7 +63,7 @@ Read and follow [intake.md](intake.md) in full. **Do not stop after intake.** Unlike standalone intake, the start agent continues immediately. -Note the UR number created (e.g. `UR-003`) — you will need it for the next steps. Under Linear, also keep the milestone id in context. +Note the Issue slug created (e.g. `UR-003`) — you will need it for the next steps. Under Linear, also keep the milestone id in context. **Number conflict guard:** - **Markdown:** Intake scans existing UR folders and uses max+1. Capture scans existing REQ files across backlog, working, and archive and uses max+1. Both use zero-padded 3-digit numbers. If the filesystem has gaps (e.g., UR-001, UR-003), the next number is max+1 (UR-004), not the gap fill (UR-002). diff --git a/agents/tracker/do-work-io.md b/agents/tracker/do-work-io.md index 9214edc..7e7c616 100644 --- a/agents/tracker/do-work-io.md +++ b/agents/tracker/do-work-io.md @@ -6,6 +6,20 @@ Implements the tracker port (`agents/tracker/port.md`) with **do-work.io as the --- +## Product naming vs wire (frozen) + +| Surface | Value | +|---------|--------| +| **Product noun** (UI, agent prose) | **Issue** — top-level brief container | +| **Agent / wire id** | slug **`UR-NNN`** (zero-padded); param name **`ur`** | +| **MCP / capability wire** | **`ur.*`** / **`ur_*`** (`ur.create`, `ur_create`, …) | +| **Port ops** | still `create_ur`, `read_ur`, `list_urs`, … | +| **DB tables** | `issues`, `issue_artifacts` (FKs `issue_id`) | + +**Do not invent** `issue.create`, `issue_create`, `ISSUE-NNN`, or param `issue` for MCP calls. Wire stays `ur.*` until a deliberate product capability cutover. Markdown on-disk path `.do-work/user-requests/` is the **markdown backend only** — not the do-work-io store. + +--- + ## When to load After config load and backend resolution (`port.md` + Load Config **7c**): @@ -25,9 +39,9 @@ Do **not** load this file when backend is `markdown`, `linear`, or `sqlite`. | Entity | Home | |--------|------| | Product container | do-work.io `projects` row; identity = **slug**; REST id = ULID | -| UR | `user_requests` row; agent id = slug `UR-NNN` | +| **Issue** | `issues` row; agent id = slug `UR-NNN`; wire param `ur` | | REQ | `requirements` row; agent id = slug `REQ-NNN` | -| Ideate / clarifications / verify / close | `ur_artifacts` (`kind`) | +| Ideate / clarifications / verify / close | `issue_artifacts` (`kind`) | | Decisions | `decisions` (append-only) | | Run notes | `run_notes` | | Gate locks | **local** `{project}/.do-work/state/gate-owner.md` only | @@ -35,9 +49,9 @@ Do **not** load this file when backend is `markdown`, `linear`, or `sqlite`. ### Hard rules 1. **No dual-write** — do not treat `REQ-*.md` / `user-requests/` / Linear / `work.db` as live truth. -2. **Slugs at the agent surface** — pass `project` (slug from `tracker.dowork.project`) plus `ur` / `req` slugs. ULIDs are accepted by the server but agents should use slugs. +2. **Slugs at the agent surface** — pass `project` (slug from `tracker.dowork.project`) plus `ur` / `req` slugs (`ur` = Issue slug `UR-NNN`). ULIDs are accepted by the server but agents should use slugs. 3. **REQ status underscore** — `in_progress` (never store `in-progress`). -4. **URs have no status** — closure is `closed_at` from `write_close_report`. +4. **Issues have no status** — closure is `closed_at` from `write_close_report`. 5. **`archived` is not a status** — `req.archive` is a separate gate (`done` + `closure_proof` + all AC checked). 6. **`agent_id` is advisory** — any of the owning user's tokens may heartbeat/unblock. 7. **Rediscover tools** — `search_tool` the published underscore wire name first, then the dotted capability id; `use_tool` / MCP `tools/call` with the **observed** qualified name. Never hard-code a host-specific `dowork__…` / `server__tool` string. @@ -70,7 +84,7 @@ Published MCP **wire name** is the Grok-safe form of the capability id (`.` → ## Hard-stop template -When `tracker.backend` is **`do-work-io`**, an unusable MCP mount, PAT, project slug, or backend doc is a **hard stop**. **Never** silent-fallback to markdown, Linear, or sqlite. **Never** invent local UR/REQ files as a substitute store. +When `tracker.backend` is **`do-work-io`**, an unusable MCP mount, PAT, project slug, or backend doc is a **hard stop**. **Never** silent-fallback to markdown, Linear, or sqlite. **Never** invent local Issue/REQ files as a substitute store. ### Operator-facing message (use as template) @@ -79,7 +93,7 @@ HARD STOP: do-work-io tracker backend is configured but MCP/PAT/project is not u do-work will not fall back to markdown, Linear, or sqlite work-item storage while tracker.backend is "do-work-io". -No local REQ/UR files, Linear issues, or work.db rows were invented. +No local REQ/Issue files, Linear issues, or work.db rows were invented. What failed: .md`, `REQ-M2-001-.md`. - Run loop halts at the end of each milestone's REQs and prompts for the deploy gate. - Deploy-gate sign-off is non-delegable human confirmation. @@ -25,7 +25,7 @@ When a UR file contains both: - `active-milestone.md` — single line, current milestone identifier (e.g. `M1`). - `milestones.md` — checklist of all milestones with status: `pending` / `captured` / `running` / `deployed`. -Milestone mode is **implicit** — triggered by UR shape, not a flag. URs that do not match the trigger continue to behave as before. The `/saas-thesis` skill produces UR files with the correct shape for handoff. +Milestone mode is **implicit** — triggered by Issue shape, not a flag. Issues that do not match the trigger continue to behave as before. The `/saas-thesis` skill produces Issue briefs with the correct shape for handoff. ## Parallel Execution diff --git a/references/field-lessons.md b/references/field-lessons.md index 9b59cb1..c03faa8 100644 --- a/references/field-lessons.md +++ b/references/field-lessons.md @@ -181,3 +181,31 @@ Related to §1 (symlinked vendor) but distinct: the symlink **works for running |---------|--------------|----------------| | Playwright `screenshot ` of a Vite SPA is a blank dark page; every route PNG is the same tiny size | The CLI captures the empty `#app` shell before Vue mounts | Use `--wait-for-selector` on a real heading/testid and `--wait-for-timeout`. Re-vision the PNG. If it is still blank, verdict is `not-reached`, not `closed` | + +## 26. Close subagent must have Shell (or suite output) + +| Symptom | Likely cause | Default action | +|---------|--------------|----------------| +| Close cannot live-walk and cannot honestly emit `degraded:evidence-by-test` | Close was dispatched as a file-only subagent (no Shell / no Playwright) | Parent must grant **Shell** so close can run the covering suite (and a browser for web walks). If the harness cannot, the parent runs the suite and passes **exit code + passing/failing test names** into close. Do not treat unread test source as a passing suite unless the operator explicitly authorizes that fallback | + +## 27. do-work-io `req.get` omits body — snapshot locally + +| Symptom | Likely cause | Default action | +|---------|--------------|----------------| +| Verify/audit/worker cannot see Task, Integration, or Verification Steps after a successful `req.get` | Server `ReqView` / `ReqGetResult` does not map `body`, `layer`, `size`, `entry_point`, `terminal_state`, `suite` even though create/update persist them | Not a bad request (get takes only `{project, req}`). Reconstruct from UR artifacts + ACs + files, write a snapshot under `{project}/.do-work/state/REQ-NNN.body.md` for `check-acceptance-evidence.sh` and the worker prompt, and `req.update` the body so it is stored. Do not treat missing body as a coverage miss. Product fix is adding those fields to `ReqView`. | + + +## 28. After worktree create: read and edit only under the worktree path + +| Symptom | Likely cause | Default action | +|---------|--------------|----------------| +| Worker implements against the wrong schema/names (or patches tests that don't match the integration base) while the worktree is correct | Main checkout has **dirty WIP** on the same paths; tools defaulted to `{project}/…` instead of `{project}/.worktrees/req-…/…` | After W2/W3.5, treat the **worktree absolute path** as CWD for every read/edit/test. Never use the main checkout tree for source of truth while implementing. Dirty main files are orchestrator/operator WIP — out of bounds | +| Pest `DatasetMissing` on red tests that reference new model constants in `->with([...])` | Dataset evaluates before implementation exists; undefined class constants collapse the dataset | In red phase, use **string literals** in Pest datasets; switch to constants only after they exist (or keep literals if clearer) | + +## 29. Issue is product noun; wire stays `ur.*` / `UR-NNN` + +| Symptom | Likely cause | Default action | +|---------|--------------|----------------| +| Agent invents `issue.create` / `issue_create` / `ISSUE-NNN` / param `issue` after docs or UI say **Issue** | Product noun renamed; **wire deliberately frozen** at `ur.*` / slug `UR-NNN` / param `ur` / port ops `*_ur` | Use **Issue** in prose and reports. For MCP/port: still `ur_create`/`ur.create`, `ur`, `UR-NNN`. Tables may be `issues`/`issue_artifacts`. Do not invent capability names. On Linear: do-work Issue = Milestone; Linear Issue = REQ — never conflate | +| Markdown store probe still looks for `user-requests/` under do-work-io/sqlite/linear | Folder name is markdown-backend only; product noun change did not rename that path | Follow backend resolve: local `user-requests/` only when `backend: markdown` | + diff --git a/references/linear-paths.md b/references/linear-paths.md index ef078d0..6a96258 100644 --- a/references/linear-paths.md +++ b/references/linear-paths.md @@ -2,16 +2,16 @@ One hop from [`agents/tracker/linear.md`](../agents/tracker/linear.md). Load when implementing or auditing a path-unit (REQ-288…301) or re-filling the capability matrix. **Not** the day-to-day op index — sequences live in [linear-ops.md](linear-ops.md). -**Hierarchy lock (authoritative):** UR = **Project Milestone** on shared `product_project` (default `do-work`). **Not** Initiative-as-UR. Path narratives below may still mention historical Initiative wording in child-work tables; prefer the lock + [linear-ops.md](linear-ops.md) sequences. +**Hierarchy lock (authoritative):** do-work **Issue** (`UR-NNN`) = **Project Milestone** on shared `product_project` (default `do-work`). **Not** Initiative-as-Issue. REQs = Linear Issues (different entity). Path narratives below may still mention historical Initiative wording in child-work tables; prefer the lock + [linear-ops.md](linear-ops.md) sequences. -## Disambiguation: Milestone-as-UR vs path-milestone mode (M1/M2) +## Disambiguation: Milestone-as-Issue vs path-milestone mode (M1/M2) | Concept | What it is | Where it lives | |---------|------------|----------------| -| **Milestone-as-UR** | The Linear **Project Milestone** entity that *is* the User Request (`UR-NNN`) | On shared **product Project** (`product_project`) | -| **Path-milestone mode (M1/M2)** | Optional *delivery* mode inside one UR when the brief has `source: /saas-thesis handoff` + `### Milestones` | Cursor block `` on the **UR Project Milestone description**; Issues tagged `M1`/`M2` | +| **Milestone-as-Issue** | The Linear **Project Milestone** entity that *is* the do-work Issue (`UR-NNN`) | On shared **product Project** (`product_project`) | +| **Path-milestone mode (M1/M2)** | Optional *delivery* mode inside one Issue when the brief has `source: /saas-thesis handoff` + `### Milestones` | Cursor block `` on the **Issue Project Milestone description**; Linear Issues (REQs) tagged `M1`/`M2` | -Do **not** create Linear Initiatives for URs. Do **not** treat M1/M2 path-milestones as separate URs. +Do **not** create Linear Initiatives for do-work Issues. Do **not** treat M1/M2 path-milestones as separate Issues. --- diff --git a/references/tracker.md b/references/tracker.md index c6c223f..e5800d8 100644 --- a/references/tracker.md +++ b/references/tracker.md @@ -2,7 +2,7 @@ Deep dive for multi-tracker configuration. Hard-stop and dual-write rules are summarized in `SKILL.md` (always loaded). Canonical contracts: [agents/tracker/port.md](../agents/tracker/port.md), [agents/config.md](../agents/config.md). Runtime sequences: [agents/tracker/markdown.md](../agents/tracker/markdown.md), [agents/tracker/linear.md](../agents/tracker/linear.md), [agents/tracker/sqlite.md](../agents/tracker/sqlite.md), [agents/tracker/do-work-io.md](../agents/tracker/do-work-io.md). -Work items (URs, REQs, decisions, verify/close reports, run notes) are stored through a **tracker port**. Config key `tracker.backend` selects the implementation: +Work items (Issues / slug `UR-NNN`, REQs, decisions, verify/close reports, run notes) are stored through a **tracker port**. Config key `tracker.backend` selects the implementation: | `tracker.backend` | Behavior | |-------------------|----------| @@ -31,8 +31,8 @@ Canonical contract: `agents/tracker/port.md` + Load Config steps 6–7 / **7b** |----------|------------------| | Team | `team_id` and/or `team_key` — **hard-fail** if neither resolves | | MCP | Linear MCP tools must be discoverable — **hard-fail** with skill setup instructions if not | -| Hierarchy | **UR = Project Milestone** on shared product Project per local product; REQs = Issues with that milestone. Not Initiatives (MCP has no Initiative create tools). | -| `product_project` | Shared Linear Project (**name or UUID**) for all URs on this local product — **default empty** (not skill name `do-work`). Resolve: explicit `product_project` → `project.name` → git-root basename; `ensure_product_container` create-if-missing + **always persist UUID**. Example for this skill repo only: name `do-work`. | +| Hierarchy | **do-work Issue (`UR-NNN`) = Project Milestone** on shared product Project; **REQs = Linear Issues** with that milestone. Not Initiatives (MCP has no Initiative create tools). Product noun Issue ≠ Linear Issue. | +| `product_project` | Shared Linear Project (**name or UUID**) for all do-work Issues on this local product — **default empty** (not skill name `do-work`). Resolve: explicit `product_project` → `project.name` → git-root basename; `ensure_product_container` create-if-missing + **always persist UUID**. Example for this skill repo only: name `do-work`. | | `ur_milestone_name_pattern` | Default `{ur_id}: {title}` | | `status_map` | `backlog→Todo`, `in_progress→In Progress`, `stopped→Canceled`, `done→Done` — **hard-fail** if a mapped state is missing on the team (rename team state or override the map key) | | Labels | `Layer/`, `path-unit`, `Size/` prefixes | @@ -60,9 +60,9 @@ Canonical contract: `agents/tracker/port.md` + Load Config steps 6–7 / **7b** | `tracker.dowork.project` | `""` | Project **slug**. **Hard-fail** if empty; do not guess | | `tracker.dowork.mcp_profile` | `dowork.control` | MCP path suffix: `dowork.read` / `dowork.control` / `dowork.admin` | -**do-work-io rules:** remote MCP is the sole work-item store; never fall through to markdown, Linear, or sqlite. `status_map` is identity (`backlog` / `in_progress` / `stopped` / `done`) and **REQ-only**; URs have no status — closed-ness is `closed_at`. `/do-work upgrade migrate` **refuses** under `do-work-io`. +**do-work-io rules:** remote MCP is the sole work-item store; never fall through to markdown, Linear, or sqlite. Product noun is **Issue**; wire stays **`ur.*`** / slug **`UR-NNN`** / param **`ur`** (tables `issues` / `issue_artifacts`). `status_map` is identity (`backlog` / `in_progress` / `stopped` / `done`) and **REQ-only**; Issues have no status — closed-ness is `closed_at`. `/do-work upgrade migrate` **refuses** under `do-work-io`. -**No dual-write.** With `tracker.backend: linear`, `sqlite`, **or** `do-work-io`, that backend is the **only** work-item store. Agents must not mirror URs/REQs into another store as a second source of truth, and must not fall back when the active backend fails (hard-stop instead). After idle markdown→Linear migration (`/do-work upgrade migrate`), historical `.do-work/user-requests/` and `archive/` trees remain on disk as **read-only history** — work-item ops ignore them. +**No dual-write.** With `tracker.backend: linear`, `sqlite`, **or** `do-work-io`, that backend is the **only** work-item store. Agents must not mirror Issues/REQs into another store as a second source of truth, and must not fall back when the active backend fails (hard-stop instead). After idle markdown→Linear migration (`/do-work upgrade migrate`), historical `.do-work/user-requests/` and `archive/` trees remain on disk as **read-only history** — work-item ops ignore them. **Linear commit / branch convention** (when `backend: linear`):