From 92f7b5a834252f735940ec7613a7008b6ad81a21 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Atam=C3=A1n=20Vega?= Date: Tue, 22 Sep 2026 08:39:58 +0100 Subject: [PATCH] fix: guardrail against inventing an async trigger; route to work-story (#82) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A user with a freshly-created GitHub backlog asked the kit to build it; the agent invented an async mechanism the kit doesn't have — /builder issue comments, self-assignment, and a non-existent codex-builder.yml GitHub Actions workflow it then reported as "missing". None of that exists in the kit. Add a "how work is triggered" guardrail to coding-agent, the portable work-story playbook, and the plan-backlog / backlog-planner handoffs: - The kit works stories interactively via work-story (one session per story; launch-story to parallelize) — the only trigger it provides. - No CI/comment/label/assignment trigger and no workflow runner; never invent or scaffold one (/builder, codex-builder.yml, etc.). - If the repo genuinely has its own async coding agent (a real .github/workflows file, or GitHub Copilot's coding agent), point to its real trigger only after verifying it exists — never a fabricated one. A real opt-in async delegation is tracked as a separate follow-up. Bundle rebuilt; validator + 35 tests pass. Kit → 0.19.13. Note: #79 (plan-definition) also carries a 0.19.13 bump on its branch; if this lands first, #79 re-bumps to 0.19.14 before merging. Co-Authored-By: Claude Opus 4.8 --- .claude-plugin/plugin.json | 2 +- CHANGELOG.md | 3 +++ agents/backlog-planner.md | 2 +- agents/coding-agent.md | 8 ++++++++ codex/skills/work-story/SKILL.md | 13 +++++++++++++ plugins/fullstack-dev-kit/.codex-plugin/plugin.json | 2 +- .../fullstack-dev-kit/.cursor-plugin/plugin.json | 2 +- plugins/fullstack-dev-kit/plugin.json | 2 +- .../fullstack-dev-kit/skills/plan-backlog/SKILL.md | 4 +++- .../fullstack-dev-kit/skills/work-story/SKILL.md | 13 +++++++++++++ skills/plan-backlog/SKILL.md | 4 +++- 11 files changed, 48 insertions(+), 7 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index dccc252..3e44480 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "fullstack-dev-kit", - "version": "0.19.12", + "version": "0.19.13", "description": "Issue-to-PR workflow kit for any tech stack. Fetch a user story from your tracker (Jira, Linear, GitHub Issues, Azure DevOps) and any linked Figma designs, implement with plan approval, enforce >95% coverage and a security pass, generate e2e tests, open the PR, fix review findings, and move the ticket to review.", "license": "Apache-2.0", "homepage": "https://github.com/theam/claude-dev-kit", diff --git a/CHANGELOG.md b/CHANGELOG.md index 82b83e3..01eed82 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,9 @@ The `version` in `.claude-plugin/plugin.json` is what reaches installed clients a release is only "live" for users once that is bumped and published. ## [Unreleased] +### Fixed +- **No fabricated automation to "start" a story.** A user with a freshly-created GitHub backlog asked the kit to build it; instead of routing to `work-story`, the agent **invented** an async mechanism — `/builder` issue comments, self-assignment, and a non-existent `codex-builder.yml` GitHub Actions workflow it then said was "missing". None of that is part of the kit. Added a **"how work is triggered"** guardrail to `coding-agent`, the portable `work-story` playbook, and the `plan-backlog` / `backlog-planner` handoffs: the kit works stories **interactively** via `work-story` (one session per story; `launch-story` to parallelize), has **no CI/comment/label/assignment trigger** and ships no workflow runner, and must **never invent or scaffold one**. If the repo genuinely has its own async coding agent (a real `.github/workflows` file, or GitHub Copilot's coding agent), the kit may point to *its actual trigger* — but only after verifying it exists, never a fabricated one. A real opt-in async delegation is tracked separately. Kit → **0.19.13**. + ### Added - **Rich review artifact for `plan-backlog` (#74).** On hosts that support artifacts (Claude Code / claude.ai), a non-trivial backlog draft is now presented as a **navigable artifact** at the review step — collapsible epics → stories with acceptance criteria, labels, sizing and dependencies, plus search/filter and a table of contents — so a large backlog is easy to scan and drill into. The in-chat draft + approval question stay the gate (the artifact is a review aid, not a substitute); portable hosts (Codex/Cursor/Copilot) keep Markdown. From @santielizondo's idea. Kit → **0.19.12**. diff --git a/agents/backlog-planner.md b/agents/backlog-planner.md index df77752..25a98fc 100644 --- a/agents/backlog-planner.md +++ b/agents/backlog-planner.md @@ -34,7 +34,7 @@ Build the backlog draft per `plan-backlog`: the hierarchy plus each item's title On approval, create the items via the tracker's write adapter: **parents before children**, link children to parents, set labels/components/points where discovered, and **verify writes by read-back** where the CLI can silently no-op (e.g. GitHub). Ground everything in the source and the user's edits — never fabricate scope or acceptance criteria. ### 4. Report and hand off -Report each created item with its key/URL and the hierarchy. Each story is ready for `work-story ` → PR, closing the loop **idea → backlog → ticket → PR**. +Report each created item with its key/URL and the hierarchy. Each story is worked by running `work-story ` **interactively** (one session per story; `launch-story` to parallelize), closing the loop **idea → backlog → ticket → PR**. The kit has no batch/async, CI, or comment/label trigger and ships no workflow runner — **never invent or scaffold one** (no `/builder` comments, no `codex-builder.yml`). If the repo has its own async coding agent, point to its real trigger only after verifying it exists. ## Guardrails - Never create anything before explicit approval. diff --git a/agents/coding-agent.md b/agents/coding-agent.md index f2aad20..23ce021 100644 --- a/agents/coding-agent.md +++ b/agents/coding-agent.md @@ -80,3 +80,11 @@ Apply the gates that fit the project (detect its setup each run; see `instructio ## Reporting At every step, state plainly what passed, what failed (with output), and what was skipped. Never report a gate as passed without having run it. + +## How work is triggered — no fabricated automation + +You work a story **interactively, in this session**: `work-story` fetches the ticket, plans, implements, verifies, and opens the PR right here, with the plan-approval gate in the chat. **That is the only trigger the kit provides.** The kit has **no CI, comment, label, or assignment trigger** and ships **no GitHub Actions runner** (headless runs can't do MCP OAuth). + +- **Never invent or scaffold an automation mechanism to "start" a story** — no `/builder`-style comment conventions, no `codex-builder.yml` or any workflow file, no self-assignment ritual. If you find yourself proposing a trigger the repo doesn't already have, stop: the trigger is you, now, running `work-story`. +- A backlog created by `plan-backlog` is worked by running **`work-story `** on each item — one interactive session per story (`launch-story` opens a window per story to parallelize). There is no batch/async "build the whole backlog" button in the kit; don't improvise one. +- **If the repo genuinely has its own async coding agent** — a real workflow in `.github/workflows`, or GitHub Copilot's coding agent — you may point the user to *its actual trigger* (e.g. "assign the issue to `@copilot`"), but only after **verifying it exists by reading the repo**. Never a trigger you assumed or fabricated. That async path is the user's own tool, separate from this kit. diff --git a/codex/skills/work-story/SKILL.md b/codex/skills/work-story/SKILL.md index 59b0ec6..7021da5 100644 --- a/codex/skills/work-story/SKILL.md +++ b/codex/skills/work-story/SKILL.md @@ -77,3 +77,16 @@ user may edit or skip. No genuine loose ends → say so and skip. Never fabricat ## Reporting At every step, state plainly what passed, what failed (with output), and what was skipped. Never report a gate as passed without having run it. + +## How work is triggered — no fabricated automation +You work a story **interactively, in this session** — that is the only trigger the kit provides. +The kit has **no CI, comment, label, or assignment trigger** and ships **no workflow runner**. +- **Never invent or scaffold an automation mechanism to "start" a story** — no `/builder`-style + comment conventions, no `codex-builder.yml` or any workflow file, no self-assignment ritual. If + you're proposing a trigger the repo doesn't already have, stop: the trigger is you, running + `work-story` now. +- A `plan-backlog` backlog is worked by running **`work-story `** on each item — one + interactive session per story. There is no batch/async "build the whole backlog" in the kit. +- **If the repo genuinely has its own async coding agent** (a real `.github/workflows` file, or + GitHub Copilot's coding agent), you may point the user to *its actual trigger* — but only after + verifying it exists by reading the repo, never one you assumed. That path is the user's own tool. diff --git a/plugins/fullstack-dev-kit/.codex-plugin/plugin.json b/plugins/fullstack-dev-kit/.codex-plugin/plugin.json index 25c5922..1738814 100644 --- a/plugins/fullstack-dev-kit/.codex-plugin/plugin.json +++ b/plugins/fullstack-dev-kit/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "fullstack-dev-kit", - "version": "0.19.12", + "version": "0.19.13", "description": "Issue-to-PR workflow for any tech stack: fetch stories from Jira/Linear/GitHub/Azure and Figma designs, plan-approval gate, adaptive quality + coverage gates, e2e generation, PR creation and review.", "author": { "name": "The Agile Monkeys", diff --git a/plugins/fullstack-dev-kit/.cursor-plugin/plugin.json b/plugins/fullstack-dev-kit/.cursor-plugin/plugin.json index b3712c2..8e2438c 100644 --- a/plugins/fullstack-dev-kit/.cursor-plugin/plugin.json +++ b/plugins/fullstack-dev-kit/.cursor-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "fullstack-dev-kit", - "version": "0.19.12", + "version": "0.19.13", "description": "Issue-to-PR workflow for any tech stack: fetch stories from Jira/Linear/GitHub/Azure and Figma designs, plan-approval gate, adaptive quality + coverage gates, e2e generation, PR creation and review.", "author": { "name": "The Agile Monkeys" diff --git a/plugins/fullstack-dev-kit/plugin.json b/plugins/fullstack-dev-kit/plugin.json index 3a8b188..d42585e 100644 --- a/plugins/fullstack-dev-kit/plugin.json +++ b/plugins/fullstack-dev-kit/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", "name": "fullstack-dev-kit", - "version": "0.19.12", + "version": "0.19.13", "description": "Issue-to-PR workflow for any tech stack: fetch stories from Jira/Linear/GitHub/Azure and Figma designs, plan-approval gate, adaptive quality + coverage gates, e2e generation, PR creation and review.", "author": { "name": "The Agile Monkeys", diff --git a/plugins/fullstack-dev-kit/skills/plan-backlog/SKILL.md b/plugins/fullstack-dev-kit/skills/plan-backlog/SKILL.md index b18bea4..118ab5a 100644 --- a/plugins/fullstack-dev-kit/skills/plan-backlog/SKILL.md +++ b/plugins/fullstack-dev-kit/skills/plan-backlog/SKILL.md @@ -115,7 +115,9 @@ If the adapter's backend is not authenticated (MCP connector not authorized, `gh ## 7. Handoff -List the created items with their keys/URLs and hand off: each story is ready for **`work-story ` → PR**. That completes the loop **idea → backlog → ticket → PR**. +List the created items with their keys/URLs and hand off: each story is worked by running **`work-story `** on it — one **interactive** session per story (the plan is approved in the chat, then it implements and opens the PR); `launch-story` opens a window per story to run several in parallel. That completes the loop **idea → backlog → ticket → PR**. + +**Don't invent a way to "build the backlog" automatically.** The kit has no batch/async, CI, comment, label, or assignment trigger, and ships no workflow runner — never propose or scaffold one (no `/builder` comments, no `codex-builder.yml`). If the repo already has its *own* async coding agent (a real `.github/workflows` file, or GitHub Copilot's coding agent), you may point the user to its actual trigger **after verifying it exists** — never a fabricated one. ## Guardrails diff --git a/plugins/fullstack-dev-kit/skills/work-story/SKILL.md b/plugins/fullstack-dev-kit/skills/work-story/SKILL.md index 59b0ec6..7021da5 100644 --- a/plugins/fullstack-dev-kit/skills/work-story/SKILL.md +++ b/plugins/fullstack-dev-kit/skills/work-story/SKILL.md @@ -77,3 +77,16 @@ user may edit or skip. No genuine loose ends → say so and skip. Never fabricat ## Reporting At every step, state plainly what passed, what failed (with output), and what was skipped. Never report a gate as passed without having run it. + +## How work is triggered — no fabricated automation +You work a story **interactively, in this session** — that is the only trigger the kit provides. +The kit has **no CI, comment, label, or assignment trigger** and ships **no workflow runner**. +- **Never invent or scaffold an automation mechanism to "start" a story** — no `/builder`-style + comment conventions, no `codex-builder.yml` or any workflow file, no self-assignment ritual. If + you're proposing a trigger the repo doesn't already have, stop: the trigger is you, running + `work-story` now. +- A `plan-backlog` backlog is worked by running **`work-story `** on each item — one + interactive session per story. There is no batch/async "build the whole backlog" in the kit. +- **If the repo genuinely has its own async coding agent** (a real `.github/workflows` file, or + GitHub Copilot's coding agent), you may point the user to *its actual trigger* — but only after + verifying it exists by reading the repo, never one you assumed. That path is the user's own tool. diff --git a/skills/plan-backlog/SKILL.md b/skills/plan-backlog/SKILL.md index b18bea4..118ab5a 100644 --- a/skills/plan-backlog/SKILL.md +++ b/skills/plan-backlog/SKILL.md @@ -115,7 +115,9 @@ If the adapter's backend is not authenticated (MCP connector not authorized, `gh ## 7. Handoff -List the created items with their keys/URLs and hand off: each story is ready for **`work-story ` → PR**. That completes the loop **idea → backlog → ticket → PR**. +List the created items with their keys/URLs and hand off: each story is worked by running **`work-story `** on it — one **interactive** session per story (the plan is approved in the chat, then it implements and opens the PR); `launch-story` opens a window per story to run several in parallel. That completes the loop **idea → backlog → ticket → PR**. + +**Don't invent a way to "build the backlog" automatically.** The kit has no batch/async, CI, comment, label, or assignment trigger, and ships no workflow runner — never propose or scaffold one (no `/builder` comments, no `codex-builder.yml`). If the repo already has its *own* async coding agent (a real `.github/workflows` file, or GitHub Copilot's coding agent), you may point the user to its actual trigger **after verifying it exists** — never a fabricated one. ## Guardrails