From 6e0afa955265a1a2baa8df9371c135d4e82aefd7 Mon Sep 17 00:00:00 2001 From: Mandar Nilange Date: Sat, 2 May 2026 11:30:20 +0530 Subject: [PATCH] feat(skills): default to creating new files, confirm before editing existing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit All three skills bump to 0.2.0 with a unified Modification policy: - Default behaviour is "create new files alongside existing ones". - Editing an existing agent / pipeline / node / prompt / schema (or, for template-author, an existing shipped template / registry / doc / test) requires explicit user intent — words like "update", "edit", "modify", "extend", "rewrite", or naming the specific file. - Per-file confirmation via AskUserQuestion (Claude Code) or the host agent's interactive-prompt tool. Never silently overwrite. - agentforge-debug splits confirmation into two categories: state mutation (gate / cancel / continue) and file edits (prompts, schemas). - agentforge-template-author flags in-place edits to a shipped template as a breaking change and defaults to forking when intent is unclear. Top-level skills/CHANGELOG.md gains a "modification policy sweep" entry explaining the bump rationale (minor — additive guidance, no trigger changes). --- skills/CHANGELOG.md | 18 ++++++ skills/agentforge-debug/CHANGELOG.md | 15 +++++ skills/agentforge-debug/SKILL.md | 51 ++++++++++++---- .../agentforge-template-author/CHANGELOG.md | 15 +++++ skills/agentforge-template-author/SKILL.md | 51 +++++++++++++++- skills/agentforge-workflow/CHANGELOG.md | 12 ++++ skills/agentforge-workflow/SKILL.md | 60 ++++++++++++++++++- 7 files changed, 206 insertions(+), 16 deletions(-) diff --git a/skills/CHANGELOG.md b/skills/CHANGELOG.md index a9f770b..6ea1390 100644 --- a/skills/CHANGELOG.md +++ b/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 diff --git a/skills/agentforge-debug/CHANGELOG.md b/skills/agentforge-debug/CHANGELOG.md index f923793..7f28433 100644 --- a/skills/agentforge-debug/CHANGELOG.md +++ b/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. diff --git a/skills/agentforge-debug/SKILL.md b/skills/agentforge-debug/SKILL.md index b5316e4..21fc3c0 100644 --- a/skills/agentforge-debug/SKILL.md +++ b/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/.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 `. +2. If the LLM hallucinated a missing field, propose tightening + `prompts/.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 ` — + 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 diff --git a/skills/agentforge-template-author/CHANGELOG.md b/skills/agentforge-template-author/CHANGELOG.md index 9599a2f..115db84 100644 --- a/skills/agentforge-template-author/CHANGELOG.md +++ b/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 ` 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 + (`-secure`, `-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. diff --git a/skills/agentforge-template-author/SKILL.md b/skills/agentforge-template-author/SKILL.md index b8ebf2c..8a3af90 100644 --- a/skills/agentforge-template-author/SKILL.md +++ b/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//` 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 `; 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 diff --git a/skills/agentforge-workflow/CHANGELOG.md b/skills/agentforge-workflow/CHANGELOG.md index e8b4fcc..f5f0e40 100644 --- a/skills/agentforge-workflow/CHANGELOG.md +++ b/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. diff --git a/skills/agentforge-workflow/SKILL.md b/skills/agentforge-workflow/SKILL.md index 2a2fcbf..dc9e13f 100644 --- a/skills/agentforge-workflow/SKILL.md +++ b/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,7 +163,9 @@ 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). @@ -171,6 +173,57 @@ Write the full directory per `references/scaffold.md`. After writing: (`npx @mandarnilange/agentforge run-pipeline --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/.agent.yaml` + - New pipeline → `pipelines/.pipeline.yaml` + - New schema → `schemas/.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-.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/.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