initializ · initializ-mk · May 20, 2026 · May 20, 2026
diff --git 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