feat(skills): default to creating new files, confirm before editing existing

skills/CHANGELOG.md

@@ -41,6 +41,24 @@ next install.
 
 - _add entries here as they merge_
 
+### 2026-05-02 (modification policy sweep)
+
+- **`agentforge-workflow` 0.2.0** — added a Modification policy:
+  default to creating new files; require per-file confirmation
+  (`AskUserQuestion` or equivalent) before editing existing agents /
+  pipelines / nodes / prompts / schemas. Per-skill changelog:
+  [`agentforge-workflow/CHANGELOG.md`](agentforge-workflow/CHANGELOG.md).
+- **`agentforge-template-author` 0.2.0** — same policy, applied to shipped
+  templates: default to forking when the user hasn't asked to edit;
+  in-place edits to a shipped template are flagged as a breaking change.
+  See [`agentforge-template-author/CHANGELOG.md`](agentforge-template-author/CHANGELOG.md).
+- **`agentforge-debug` 0.2.0** — same policy, applied to fix-path edits
+  (prompts, schemas). Existing state-mutation confirmation rule
+  preserved. See [`agentforge-debug/CHANGELOG.md`](agentforge-debug/CHANGELOG.md).
+
+Bump rationale: minor version. New behavioural guidance, additive prose
+in `SKILL.md` and the *Hard rules* list. Trigger conditions unchanged.
+
 ### 2026-05-02
 
 - **`agentforge-template-author` 0.1.0** — initial release. Guides

skills/agentforge-debug/CHANGELOG.md

@@ -1,5 +1,20 @@
 # `agentforge-debug` changelog
 
+## 0.2.0 — 2026-05-02
+
+- Strengthened the **confirm-before-mutate** rule into two explicit
+  categories: state mutation (gate decisions, run cancel / continue, claim
+  clear) and file edits (prompts, schemas, agent / pipeline YAML).
+  Previous version only covered state mutation explicitly.
+- File edits now require per-file confirmation via `AskUserQuestion` or
+  the host agent's interactive-prompt tool. Substantive rewrites default
+  to *creating a new file alongside* the existing one; one-line tweaks
+  may edit in place after explicit confirmation.
+- The fix-path examples in the flow now read "propose, do not edit yet"
+  rather than implying immediate edits.
+- Added the rule to the *Hard rules* list.
+- No trigger-condition changes.
+
 ## 0.1.0 — 2026-05-02
 
 Initial release.

skills/agentforge-debug/SKILL.md

@@ -12,7 +12,7 @@ description: >
 license: MIT
 metadata:
   author: mandarnilange
-  version: "0.1.0"
+  version: "0.2.0"
 ---
 
 # AgentForge Pipeline Debug
@@ -126,23 +126,45 @@ reversible action first**, then escalating options.
 
 For example, on a schema-invalid failure:
 1. Inspect the agent's last LLM output via dashboard or logs.
-2. If the LLM hallucinated a missing field, the prompt likely needs a
-   tightening — propose a one-line addition to `prompts/<agent>.system.md`.
-3. If the schema itself is wrong, point at the schema file and propose the
-   minimum change.
-4. Re-run only the failed agent: `agentforge run --continue <run-id>`.
+2. If the LLM hallucinated a missing field, propose tightening
+   `prompts/<agent>.system.md` — but **do not edit the file yet**. State
+   the proposed change in chat first.
+3. If the schema itself is wrong, point at the schema file and propose
+   the minimum change. Again, do not edit yet.
+4. Re-run only the failed agent: `agentforge run --continue <run-id>` —
+   only after the user authorises.
 
 Do not skip to "abort and re-start the pipeline" unless the run is
 unrecoverable.
 
-### 5. Confirm before mutating state
+### 5. Confirm before mutating state OR editing files
 
-Any action that changes shared state — approving a gate, cancelling a run,
-re-running an agent, force-clearing a stuck claim — requires explicit user
-confirmation. State your understanding, the proposed action, and the
-expected outcome. Wait.
+Two categories of confirmation:
 
-Read-only investigation does not need confirmation.
+**State mutation** — approving a gate, cancelling a run, re-running an
+agent, force-clearing a stuck claim. State your understanding, the
+proposed action, and the expected outcome. Wait.
+
+**File edits** — modifying a prompt, a schema, an agent / pipeline /
+node YAML, or anything else under `.agentforge/`. **Default to creating
+a new file alongside the existing one** if your fix involves a substantive
+rewrite (e.g. a redesigned prompt). For surgical changes (one-line tweak),
+ask explicit confirmation per file.
+
+Use `AskUserQuestion` (Claude Code) or the host agent's interactive-prompt
+tool when available. Otherwise, propose in chat and wait for a yes/no:
+
+> *"Proposed change to `prompts/analyst.system.md`: add 'You MUST include
+> a `summary` field in your output JSON.' as a new sentence at the end of
+> the 'Output contract' section. Apply this edit? (y/n)"*
+
+One question per file. Read-only investigation (running `agentforge get
+...` commands, reading logs, inspecting the dashboard) does **not** need
+confirmation.
+
+**Never silently overwrite** a prompt, schema, or agent file. The user's
+prior version may be the "right" version; your proposed edit is a
+hypothesis until they accept it.
 
 ## Hard rules
 
@@ -157,6 +179,11 @@ Read-only investigation does not need confirmation.
   disagree, the state store is the source of truth — read it directly.
 - **Propose one fix at a time.** Avoid stacked changes that make it
   impossible to know which one solved the problem.
+- **Confirm every file edit explicitly.** Use `AskUserQuestion` or the
+  host agent's interactive-prompt tool. Default to creating a new file
+  alongside the existing one for substantive rewrites; one-line tweaks
+  may edit in place after explicit confirmation. Never overwrite
+  silently.
 
 ## What success looks like
 

skills/agentforge-template-author/CHANGELOG.md

@@ -1,5 +1,20 @@
 # `agentforge-template-author` changelog
 
+## 0.2.0 — 2026-05-02
+
+- Added a **Modification policy** section. Default behaviour is *create
+  a new template directory*. Editing a shipped template, the registry,
+  an existing test, or `docs/templates.md` requires explicit user intent
+  ("update", "edit", "modify") and per-file confirmation via
+  `AskUserQuestion` or the host agent's interactive-prompt tool. Editing
+  a shipped template is flagged as a **breaking change** because end
+  users `agentforge init --template <name>` against it.
+- When the user's request overlaps with an existing template but they
+  haven't asked to edit it, the skill now defaults to forking
+  (`<name>-secure`, `<name>-v2`) instead of in-place modification.
+- Added the rule to the *Hard rules* list.
+- No trigger-condition changes.
+
 ## 0.1.0 — 2026-05-02
 
 Initial release.

skills/agentforge-template-author/SKILL.md

@@ -13,7 +13,7 @@ description: >
 license: MIT
 metadata:
   author: mandarnilange
-  version: "0.1.0"
+  version: "0.2.0"
 ---
 
 # AgentForge Template Author
@@ -186,7 +186,9 @@ Required files at the top of the template directory:
 
 ### 10. Emit and stop
 
-Write the directory tree per `references/template-anatomy.md`. Show the
+Write the directory tree per `references/template-anatomy.md`. **Default
+to creating new files** — see the *Modification policy* below before
+touching any existing template, registry, or doc. After writing, show the
 contributor:
 
 1. The exact file tree you wrote.
@@ -203,6 +205,47 @@ contributor:
 Do **not** open the PR. Do **not** push. Stop here unless the contributor
 explicitly asks for the next step.
 
+## Modification policy
+
+This skill ships changes into the repo, not into a user's project — every
+edit becomes a PR that other people will live with. Be conservative.
+
+**Default behaviour: create a new template directory. Never touch an
+existing shipped template, registry file, doc, or test unless the user
+explicitly says "update", "edit", "modify", or names the file.**
+
+Three cases:
+
+1. **New template (greenfield).** Create a brand-new directory under
+   `packages/{core,platform}/src/templates/<new-name>/` and a brand-new
+   test file. The registry auto-discovers — no registry edit needed.
+   `docs/templates.md` is the only existing file you need to *append* to;
+   confirm the addition before writing.
+
+2. **The user explicitly asks to edit an existing template** (e.g.
+   *"update `simple-sdlc` to add a security agent"*). Before each file
+   edit, ask explicit confirmation. Use `AskUserQuestion` (Claude Code)
+   or the host agent's interactive-prompt tool when available. Otherwise,
+   state the proposed change in chat and wait for a yes/no:
+
+   > *"`packages/core/src/templates/simple-sdlc/pipelines/simple-sdlc.pipeline.yaml`
+   > currently has 3 phases. Adding a `security` phase between
+   > `architecture` and `implementation` requires renumbering. Apply
+   > this edit? (y/n)"*
+
+   One question per file. Modifying a shipped template can break end
+   users on `agentforge init --template <name>`; warn the contributor
+   that this is a **major** version bump and a breaking change.
+
+3. **The user has NOT signalled an edit intent** but the work overlaps
+   with an existing template. Default to forking: create a new template
+   directory (e.g. `simple-sdlc-secure/`) instead of modifying the
+   existing one. Confirm naming with the contributor.
+
+**Never silently overwrite a shipped template, the registry file, an
+existing test, or `docs/templates.md`.** Every edit to existing files in
+this repo needs an explicit go-ahead.
+
 ## Hard rules
 
 - **Do not invent registry fields.** `template.json` must match the schema in
@@ -218,6 +261,10 @@ explicitly asks for the next step.
   these.
 - **Tests required.** A template without a parse test should not merge. See
   `references/test-and-publish.md`.
+- **Default to creating a new template. Confirm before editing existing
+  ones.** See *Modification policy* above. Use `AskUserQuestion` or the
+  host agent's interactive-prompt tool. Editing a shipped template is a
+  breaking change — warn the contributor.
 
 ## What success looks like
 

skills/agentforge-workflow/CHANGELOG.md

@@ -1,5 +1,17 @@
 # `agentforge-workflow` changelog
 
+## 0.2.0 — 2026-05-02
+
+- Added a **Modification policy** section. Default behaviour is now
+  *create new files*; the skill must scan `.agentforge/` first and only
+  edit existing agent / pipeline / node / prompt / schema files when the
+  user explicitly says "update", "edit", "modify", "extend", or "rewrite"
+  (or names a specific file). Edits require per-file confirmation via
+  `AskUserQuestion` or the host agent's interactive-prompt tool.
+- Added the rule to the *Hard rules* list as well so it surfaces alongside
+  schema and budget constraints.
+- No trigger-condition changes; existing prompts still fire the skill.
+
 ## 0.1.0 — 2026-05-02
 
 Initial release.

skills/agentforge-workflow/SKILL.md

@@ -11,7 +11,7 @@ description: >
 license: MIT
 metadata:
   author: mandarnilange
-  version: "0.1.0"
+  version: "0.2.0"
 ---
 
 # AgentForge Workflow
@@ -163,14 +163,67 @@ schema — do not over-specify; the agent fills it in.
 
 ### 8. Emit the scaffold
 
-Write the full directory per `references/scaffold.md`. After writing:
+Write the full directory per `references/scaffold.md`. **Default to creating
+new files** — see the *Modification policy* below before touching anything
+that already exists. After writing:
 
 1. Tell the user the exact CLI command to validate it
    (`npx @mandarnilange/agentforge validate` from the project root).
 2. Show the run command for their pipeline
    (`npx @mandarnilange/agentforge run-pipeline <name> --input ...`).
 3. Stop. Do not run the pipeline yourself unless the user asks.
 
+## Modification policy
+
+**Default behaviour: create new files. Never overwrite or edit existing
+agent / pipeline / node / prompt / schema files unless the user has
+explicitly asked you to "update", "edit", "modify", "fix", or "rewrite"
+the existing one.**
+
+Before this skill runs, scan `.agentforge/` to see what already exists:
+
+```bash
+ls .agentforge/agents .agentforge/pipelines .agentforge/nodes .agentforge/prompts .agentforge/schemas 2>/dev/null
+```
+
+Three cases:
+
+1. **Empty `.agentforge/` (greenfield).** Create everything. No
+   confirmation needed.
+
+2. **Existing `.agentforge/` and the user said "update", "edit", "modify",
+   "extend", "rewrite", or named a specific file to change.** You may
+   edit, but **before each edit**, ask explicit confirmation. Use
+   `AskUserQuestion` (Claude Code) or the host agent's interactive-prompt
+   tool when available. Otherwise, state the proposed change in chat and
+   wait for a yes/no:
+
+   > *"`agents/analyst.agent.yaml` already exists with executor `pi-ai`
+   > and budget $0.10 / 40k tokens. You asked to swap the model to
+   > `claude-haiku-4-5`. Apply this edit? (y/n)"*
+
+   One question per file. Batch only when the changes are mechanically
+   identical (e.g. version bump across three agent files).
+
+3. **Existing `.agentforge/` and the user has NOT signalled an edit
+   intent.** Default to **adding new files alongside** the existing ones:
+   - New agent → `agents/<new-name>.agent.yaml`
+   - New pipeline → `pipelines/<new-name>.pipeline.yaml`
+   - New schema → `schemas/<new-type>.schema.yaml`
+
+   Pick a name that doesn't collide. If a name collision is unavoidable
+   (e.g. user asked for "another analyst" and `analyst.agent.yaml`
+   already exists), confirm before reusing the name — propose
+   `analyst-v2.agent.yaml` or `analyst-<domain>.agent.yaml` first and
+   ask which they prefer.
+
+**Never silently overwrite.** A file that exists is the user's prior
+work; treat it as authoritative until they say otherwise.
+
+When unsure whether the user is asking for "extend" vs "edit", ask. The
+cost of one clarifying question is much lower than the cost of clobbering
+their pipeline.
+
 ## Hard rules
 
 - **Do not invent schema fields.** Every YAML key you emit must exist in
@@ -185,6 +238,9 @@ Write the full directory per `references/scaffold.md`. After writing:
   prototype stage. Use `prompts/<agent>.system.md`.
 - **Never modify shipped templates in place.** Copy them into the user's
   `.agentforge/` directory first, then edit.
+- **Default to creating new files. Confirm before editing existing ones.**
+  See *Modification policy* above. Use `AskUserQuestion` or the host
+  agent's interactive-prompt tool. Never silently overwrite.
 
 ## What success looks like