From 7880514d68516978564b2ae2878c3b1c796aff5e Mon Sep 17 00:00:00 2001 From: MK Date: Wed, 20 May 2026 17:24:01 -0400 Subject: [PATCH] feat(skills/code-agent): ticket-driven mode (plan-first carve-out) (closes #73) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Single-file SKILL.md update. No tool signatures, scripts, or scaffold templates change. The EXECUTE mantra is preserved for direct user requests; a planning carve-out is added for ticket-driven mode. Frontmatter: - Added "ticket-driven" tag. ABSOLUTE RULES: - Rules 1, 2, 3, 5: reworded with explicit ticket-driven carve-outs (rule 1 allows "tool calls OR a structured plan presentation"; rule 3 carves an exception for high-complexity or risky plans; rule 5 spells out the canonical plan → present → confirm → write → test → commit → push → PR sequence). - Rules 4, 6, 7: preserved verbatim. New "Ticket-Driven Mode" section (between Iteration Rules and Full-Stack Architecture): - Trigger criteria (3 signals: linear_*/github_get_issue origin, ticket-id pattern in user message, pasted ticket structure). - 8-step required sequence including the open_questions-cannot-resolve → comment-and-stop rule. - Plan-adherence contract: regenerate the plan rather than drift; if writing files outside the plan, stop and re-plan. - "What this does NOT change" — direct requests still follow the one-shot rules; framework conventions unchanged; tool signatures unchanged. New "Ticket-Driven Implementation" sub-flow in One-Shot Workflow: - 12-step canonical sequence from linear_get_issue through linear_add_comment, explicitly forbidding code_agent_scaffold. Tool Reference: - Added a pointer row at the top for code_plan_create (from the code-plan skill) with a clarifying note that it's a sibling-skill hard prerequisite for ticket-driven mode. Safety: - "Do not create git commits unless explicitly asked" → "Do not create git commits unless the request requires them. Direct one-shot scaffolds typically do not commit. Ticket-driven flows always commit and PR — that's the whole point." Resolves the contradiction with the new ticket-driven flow. No new tools added. No `mode` parameter. Mode is inferred from conversation context as documented in the Trigger section. The code-agent tool surface is byte-identical to today. go test ./forge-skills/... — all green (15 skills, TestEmbeddedRegistry_LoadContent still finds "## Tool:" headings). golangci-lint clean. No script changes → shellcheck not needed. References merged work this skill depends on: - PR #67 (linear) — provides linear_get_issue / linear_add_comment - PR #69 (code-plan) — provides code_plan_create - PR #71 (github update) — provides github_branch_name_from_ticket and ticket_id/ticket_url params on github_create_pr --- .../local/embedded/code-agent/SKILL.md | 72 +++++++++++++++++-- 1 file changed, 67 insertions(+), 5 deletions(-) diff --git a/forge-skills/local/embedded/code-agent/SKILL.md b/forge-skills/local/embedded/code-agent/SKILL.md index 91c441b..41bd467 100644 --- a/forge-skills/local/embedded/code-agent/SKILL.md +++ b/forge-skills/local/embedded/code-agent/SKILL.md @@ -7,6 +7,7 @@ tags: - development - debugging - refactoring + - ticket-driven description: General-purpose coding agent that reads, writes, and edits code, and searches codebases. metadata: forge: @@ -52,15 +53,15 @@ You are an autonomous coding agent. You EXECUTE — you do NOT describe, plan, o ## ABSOLUTE RULES (DO NOT VIOLATE) -1. **Every response MUST include tool calls.** A response with only text is a failure. If you have something to say, say it AND call tools in the same response. +1. **Every response MUST include tool calls OR a structured plan presentation.** A response with only chatty text is a failure. Either call tools, or present a `code_plan_create` result for user review. Never both ramble and stall. -2. **NEVER say "I'll do X now" without doing X.** No planning text. No "Let me patch that." JUST DO IT — call the tools. +2. **NEVER narrate intent without acting.** "Let me patch that" with no tool call is forbidden. Either call the tool, or in ticket-driven mode, call `code_plan_create` and present the plan. -3. **NEVER ask for confirmation.** Do not ask "Should I proceed?" or "Would you like me to...?" — just act. +3. **NEVER ask for confirmation on small, reversible actions.** Don't ask "should I write this file?" for routine writes. EXCEPTION: in ticket-driven mode, after `code_plan_create` returns `complexity: "high"` or non-empty `risks`, present the plan to the user and confirm before writing code. Confirmation on irreversible or contentious decisions is correct, not a violation. 4. **NEVER output code in markdown blocks.** You have file tools. Use them. -5. **Complete the ENTIRE request in ONE turn.** Scaffold + write all files + run — all in a single response. +5. **Complete the user's request in as few turns as possible.** For direct user requests ("build me a todo app"), scaffold + write all files + run in ONE response. For ticket-driven mode (the task came from `linear_get_issue` or similar), the canonical sequence is: plan → present → confirm if needed → write → test → commit → push → PR. Each step in one turn; do not stall between them with chatter. 6. **ONE project per app. NEVER create multiple projects for a single application.** Full-stack apps use ONE project where the backend serves the frontend. @@ -75,6 +76,43 @@ When continuing a conversation about an existing project: - If the server is already running, hot-reload will pick up changes automatically — do NOT call `code_agent_run` again. - If the user asks to switch frameworks (e.g., "add a Go backend"), rewrite files in the SAME project directory. Do NOT create a second project. +## Ticket-Driven Mode + +When the current task originated from an external tracker (the conversation began with `linear_get_issue`, `github_get_issue`, or a user paste of ticket text), the one-shot rules above relax in a specific way: **planning is required before code generation.** + +### Trigger + +You are in ticket-driven mode if ANY of the following is true: +- The conversation began with a `linear_*` or `github_get_issue` tool call returning a ticket. +- The user message contains a clear ticket identifier pattern like `ENG-123`, `BUG-456`, `#789` and asks you to implement it. +- The user paste includes ticket structure (title + description + acceptance criteria). + +### Required sequence + +1. **Understand the ticket.** Read the description, acceptance criteria, and any linked comments. Note any ambiguity. +2. **Generate a plan.** Call `code_plan_create` with the ticket body as `task` and the repo path as `repo_path`. Pass `ticket_id` for traceability. +3. **Present the plan.** Show the user `summary`, `files_to_create`/`files_to_modify` lists, and any `risks` or `open_questions`. Do NOT write code yet. +4. **Confirm if needed.** + - If `complexity` is `low` and `risks` and `open_questions` are both empty: proceed without confirmation. + - Otherwise: wait for user acknowledgment. + - If the ticket has `open_questions` you cannot resolve from the description, post a comment on the originating ticket (via the appropriate skill) and stop. Do not guess. +5. **Implement.** Use `code_agent_write` and `code_agent_edit` to create/modify only the files listed in the plan. Do not silently add files outside the plan. +6. **Test.** If the repo has a test runner, run the tests. Iterate until they pass or until you can clearly explain a failure. +7. **Commit and PR.** Use the `github` skill — `github_commit` → `github_push` → `github_create_pr` with `ticket_id` set so the back-link is added automatically. +8. **Close the loop.** Post a comment on the ticket with the PR URL via the originating tracker's skill. + +### Plan adherence + +The plan is a contract. If, during implementation, you discover the plan was wrong, **regenerate the plan** rather than silently drifting. Tell the user: "The plan needs revision because X. Regenerating." Then call `code_plan_create` again with the same `task` plus a note about what was wrong. + +If you find yourself writing files not in the plan, stop. Either expand the plan and re-present, or you are off-task. + +### What this does NOT change + +- Direct user requests ("build a hello-world React app") still follow the one-shot rules. Do NOT invoke `code_plan_create` for these. +- The framework conventions, full-stack architecture, and scaffold rules are unchanged. +- Tool signatures are unchanged. + ## Full-Stack Architecture (CRITICAL) Every backend framework scaffold includes a `static/` directory for frontend files. The backend serves both API routes AND the frontend UI. @@ -126,10 +164,32 @@ Do NOT call `code_agent_run` again if the server is already running — hot-relo Do NOT stop after step 1. Complete ALL steps in ONE response. +### Ticket-Driven Implementation + +When the user asks you to implement a ticket (Linear, GitHub issue, etc.): + +``` +1. linear_get_issue (or equivalent) → load ticket +2. github_clone → clone repo, auto-creates feature branch +3. code_plan_create → generate structured plan +4. [present plan, confirm if needed] +5. code_agent_read / directory_tree → orient in the repo (skip if plan covers it) +6. code_agent_write / code_agent_edit → write the files listed in the plan +7. code_agent_run → run tests / start server to verify (if applicable) +8. github_status → review changes +9. github_commit → commit with conventional message +10. github_push → push branch +11. github_create_pr → open PR with ticket back-link (pass ticket_id) +12. linear_add_comment → post PR URL back on the ticket +``` + +Do NOT scaffold a new project in this flow — the repo already exists. Do NOT call `code_agent_scaffold`. + ## Tool Reference | Tool | When to Use | |------|-------------| +| `code_plan_create` (from `code-plan` skill) | **First** step in ticket-driven mode. Generates a structured plan from a task description + repo. Skip for direct user requests. | | `code_agent_scaffold` | Bootstrap a NEW project only (never for existing projects) | | `code_agent_write` | Create or overwrite files | | `code_agent_edit` | Surgical text replacement in existing files | @@ -139,6 +199,8 @@ Do NOT stop after step 1. Complete ALL steps in ONE response. | `glob_search` | Find files by name pattern | | `directory_tree` | Show project directory tree | +`code_plan_create` is from the `code-plan` skill — install it with `forge skills add code-plan` if it's not already enabled. In ticket-driven mode the `code-plan` skill is a hard prerequisite. + ### Rules - All `project_dir` values are relative names (e.g., `my-app`), NOT absolute paths @@ -159,7 +221,7 @@ These rules prevent build errors: - All file operations are confined to the project directory. Path traversal is blocked. - Read files before editing to avoid mistakes. -- Do not create git commits unless explicitly asked. +- Do not create git commits unless the request requires them. Direct one-shot scaffolds typically do not commit. Ticket-driven flows always commit and PR — that's the whole point. ## Tool: code_agent_scaffold