scrumrun 1.5.0

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "scrumrun",
+  "version": "1.5.0",
+  "description": "ScrumRun: portable sprint-driven AI workflow for real software projects.",
+  "bin": {
+    "scrumrun": "bin/scrumrun.js",
+    "sr-claude": "bin/claude-install.js"
+  },
+  "files": [
+    "bin",
+    "templates",
+    "CORE.md",
+    "SPEC.md",
+    "DECISIONS.md",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test tests/*.test.js"
+  },
+  "keywords": [
+    "ai",
+    "scrum",
+    "codex",
+    "opencode",
+    "agents",
+    "sprints"
+  ],
+  "author": {
+    "name": "Leander Costa",
+    "email": "leander.dev@proton.me",
+    "url": "https://github.com/leandercosta"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/leandercosta/scrumrun.git"
+  },
+  "homepage": "https://github.com/leandercosta/scrumrun#readme",
+  "bugs": {
+    "url": "https://github.com/leandercosta/scrumrun/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/templates/codex/prompts/sc-agent.md

@@ -0,0 +1,14 @@
+---
+description: Manage review agents — add, list, run
+argument-hint: --add|-a, --list|-l, --run|-r <sprint>
+---
+
+Manage review agents in `.scrumrun/agents.md`: $ARGUMENTS
+
+If no action flag is present in `$ARGUMENTS`, list the actions below and stop without guessing an action.
+
+Actions:
+
+- `--add` (`-a`): create a new review agent in `.scrumrun/agents.md` by asking role, checks, run order, and optional technology focus first.
+- `--list` (`-l`): list all agents from `.scrumrun/agents.md` and explain their roles and checkpoints. Do not modify files.
+- `--run` (`-r`) `<sprint>`: run review agents from `.scrumrun/agents.md` against the requested sprint — all agents or a specific numbered one — and update the relevant history file with the results.

package/templates/codex/prompts/sc-backlog.md

@@ -0,0 +1,13 @@
+---
+description: Manage the sprint backlog — add, list
+argument-hint: --add|-a <sprint number or name>, --list|-l [filter]
+---
+
+Manage the sprint backlog in `.scrumrun/backlog.md`: $ARGUMENTS
+
+If no action flag is present in `$ARGUMENTS`, list the actions below and stop without guessing an action.
+
+Actions:
+
+- `--add` (`-a`) `<sprint number or name>`: add the requested sprint candidate to `.scrumrun/backlog.md` without executing code or updating sprint history. Read `.scrumrun/golden-rules.md`, `.scrumrun/config.md`, `.scrumrun/goals/main/sprint.md`, `.scrumrun/goals/main/history.md`, and `.scrumrun/backlog.md` if present. Treat the sprint as a candidate, not active work. If it exists in the sprint plan, copy its title or focus; if not, add the label as a manual candidate with details pending. Do not run implementation, agents, tests, or audits; do not change sprint status; if it already exists, report instead of duplicating.
+- `--list` (`-l`) `[filter]`: read `.scrumrun/backlog.md`, `.scrumrun/goals/main/sprint.md`, and `.scrumrun/goals/main/history.md`, then list backlog candidates showing the backlog item, the matching sprint title or focus when discoverable, whether history marks it completed, partial, or blocked, and the exact command to run it, such as `/sc-sprint --run Sprint 01`. Do not modify files.

package/templates/codex/prompts/sc-challenge.md

@@ -0,0 +1,57 @@
+---
+description: Analyze a user challenge and recommend sprint, backlog, feature, discovery, or rejection
+argument-hint: challenge description
+---
+
+Analyze this challenge against the current project and recommend the safest ScrumRun path. Do not modify files: $ARGUMENTS
+
+Read, when present:
+
+1. `AGENTS.md`;
+2. `.scrumrun/golden-rules.md`;
+3. `.scrumrun/config.md`;
+4. `.scrumrun/map.md`;
+5. `.scrumrun/project.md`;
+6. `.scrumrun/knowledge.md`;
+7. `.scrumrun/backlog.md`;
+8. `.scrumrun/goals/main/sprint.md`;
+9. `.scrumrun/goals/main/history.md`;
+10. `.scrumrun/goals/main/decisions.md`;
+11. `.scrumrun/features/*/feature.md`;
+12. `.scrumrun/features/*/sprint.md`;
+13. `.scrumrun/features/*/history.md`;
+14. `.scrumrun/features/*/decisions.md`;
+15. relevant source files needed to verify the challenge.
+
+Only use the `Approved Knowledge` section of `.scrumrun/knowledge.md` as planning truth. Pending proposals are unapproved context and must be labeled as such.
+
+The history read is mandatory when any history file exists. Use it to detect repeated work, failed attempts, blockers, partial implementations, regressions, and completed related sprints.
+
+Inspect the repository deeply enough to understand affected areas:
+
+1. product behavior;
+2. stack and local commands;
+3. architecture and entry points;
+4. auth, permissions, roles, policies, and access boundaries;
+5. data model, migrations, queues, caches, and external state;
+6. env/config, secrets handling, third-party integrations, and webhooks;
+7. tests, deployment clues, observability, and operational risk.
+
+Return:
+
+1. Challenge understanding;
+2. Approved knowledge used;
+3. Relevant evidence with file references;
+4. History findings;
+5. Impact analysis;
+6. Risks and unknowns;
+7. Options:
+   - create small sprint;
+   - add to backlog;
+   - create isolated feature lane;
+   - run discovery first;
+   - reject or defer because it conflicts with architecture, safety, product direction, or missing information;
+8. Recommendation with rationale;
+9. Suggested next command, such as `/sc-backlog --add ...`, `/sc-sprint --add ...`, `/sc-feature --add ...`, or a clarifying question.
+
+Do not create backlog items, sprint plans, feature lanes, code changes, commits, tests, or history entries unless the user explicitly asks in a follow-up command.

package/templates/codex/prompts/sc-config.md

@@ -0,0 +1,18 @@
+---
+description: Manage ScrumRun language, intake, approval, and quick-task preferences
+argument-hint: --show|-s, --lang|-l <language>, --interaction <mode>, --approval <policy>, --quick-tasks <policy>
+---
+
+Manage ScrumRun preferences in `.scrumrun/config.md`: $ARGUMENTS
+
+If no action flag is present in `$ARGUMENTS`, list the actions below and stop without guessing an action.
+
+Actions:
+
+- `--show` (`-s`): show `.scrumrun/config.md`, including language, intake, approval, quick-task, and sprint automation preferences. Do not modify files.
+- `--lang` (`-l`) `<language>`: set the response language for all ScrumRun commands in `.scrumrun/config.md`. Preserve unrelated preferences.
+- `--interaction` (`-i`) `<guided|concise|autonomous-planning|strict>`: set how natural-language intake responds. `strict` disables automatic intake.
+- `--approval` (`-a`) `<always|implementation-only>`: `always` requires approval before planning records or code changes; `implementation-only` allows the recommended planning record after intake but still requires approval before application changes.
+- `--quick-tasks` (`-q`) `<ask|allow|backlog>`: ask before a quick task, allow clearly scoped low-risk quick tasks after classification, or park them in backlog.
+
+Reject unknown values. Preserve every unrelated preference and never weaken golden rules or sprint history checks.

package/templates/codex/prompts/sc-context.md

@@ -0,0 +1,24 @@
+---
+description: Manage the token-safe ScrumRun context snapshot
+argument-hint: --build|-b, --update|-u, --show|-s, --clear|-c, --policy|-p
+---
+
+Manage ScrumRun context economy for the current project: $ARGUMENTS
+
+If no action flag is present in `$ARGUMENTS`, list the actions below and stop without guessing an action.
+
+Actions:
+
+- `--build` (`-b`): create or fully refresh `.scrumrun/context.md` from canonical ScrumRun files and targeted source inspection. Read `golden-rules.md`, `config.md`, `token-policy.md`, `map.md`, `project.md`, `knowledge.md`, `runbook.md`, active sprint/feature files, relevant history, and decisions. Do not treat the old snapshot as truth.
+- `--update` (`-u`) `[reason]`: update only the sections affected by recent work, such as current focus, decisions, risks, map pointers, and staleness triggers. Use after study, challenge, sprint creation, sprint execution, review, or knowledge changes.
+- `--show` (`-s`): show `.scrumrun/context.md` as a concise snapshot. Do not modify files.
+- `--clear` (`-c`): reset `.scrumrun/context.md` to a safe placeholder that says it is stale and must be rebuilt. Do not delete canonical project files.
+- `--policy` (`-p`): show `.scrumrun/token-policy.md` and explain how token economy applies to the current task. Do not modify files.
+
+Rules:
+
+1. `context.md` is a token-saving snapshot, not canonical truth.
+2. Never let `context.md` override golden rules, approved knowledge, sprint history, decisions, or source code.
+3. Never include `.scrumrun/vault.local.md` values.
+4. Prefer short bullets, file references, and "must read" pointers over long pasted content.
+5. If a snapshot is stale or unverifiable, mark it stale and ask whether to rebuild.

package/templates/codex/prompts/sc-decisions.md

@@ -0,0 +1,8 @@
+---
+description: Resolve pending decisions, questions, and risks one by one
+argument-hint: optional scope (default: main goal; or a feature slug)
+---
+
+Resolve pending decisions, questions, and risks one by one: $ARGUMENTS
+
+Default scope is the main goal: read `.scrumrun/goals/main/history.md` and `.scrumrun/goals/main/decisions.md`. If a feature is specified, use that feature lane's `history.md` and `decisions.md` instead. Resolve items one at a time and update the relevant decisions/history file with each resolution.

package/templates/codex/prompts/sc-feature.md

@@ -0,0 +1,16 @@
+---
+description: Manage isolated feature lanes — add, list, show, run, audit
+argument-hint: --add <description>, --list|-l, --show|-s <slug>, --run|-r <slug> <sprint>, --audit|-a <slug> <sprint>
+---
+
+Manage isolated feature lanes under `.scrumrun/features/`: $ARGUMENTS
+
+If no action flag is present in `$ARGUMENTS`, list the actions below and stop without guessing an action.
+
+Actions:
+
+- `--add` (`--new` and `-n` are legacy aliases) `<description>`: create a new isolated feature lane under `.scrumrun/features/<slug>/`. Read `AGENTS.md`, `.scrumrun/golden-rules.md`, `.scrumrun/config.md`, `.scrumrun/map.md`, `.scrumrun/project.md`, `.scrumrun/agents.md`, and `.scrumrun/goals/main/history.md`. Do not modify `.scrumrun/goals/main/sprint.md` or `.scrumrun/goals/main/history.md`. Create `feature.md`, `sprint.md`, `history.md`, and `decisions.md`. The brief must include name, reason, scope, out of scope, dependencies, risks, and assumptions; the sprint plan must be modular, auditable, and independently executable.
+- `--list` (`-l`) `[filter]`: list feature lanes under `.scrumrun/features/`, summarizing each brief, sprint status, open decisions, and next recommended sprint. Do not modify files.
+- `--show` (`-s`) `<slug>`: read the requested lane and show its `feature.md`, `sprint.md`, `history.md`, and `decisions.md` in a concise status view. Do not modify files.
+- `--run` (`-r`) `<slug> <sprint>`: run one sprint from a feature lane. Read `AGENTS.md`, `.scrumrun/golden-rules.md`, `.scrumrun/config.md`, `.scrumrun/map.md`, `.scrumrun/runbook.md`, `.scrumrun/agents.md`, and the lane's four files. Check feature history first; if the sprint is completed, partial, or blocked, stop and ask how to proceed. Otherwise follow Entenda -> Avalie Impactos -> Tire Duvidas -> Execute -> Teste, run review agents, and update the feature lane history only.
+- `--audit` (`-a`) `<slug> <sprint>`: read the lane's four files plus `AGENTS.md`, `.scrumrun/golden-rules.md`, `.scrumrun/config.md`, `.scrumrun/map.md`, and `.scrumrun/agents.md`. Review changed files from current state, verify acceptance criteria, tests, env/config handling, and safety rules. Report findings ordered by severity. Do not modify application code unless explicitly requested.

package/templates/codex/prompts/sc-fix.md

@@ -0,0 +1,21 @@
+---
+description: Record fixes and browse the fix log for future reference
+argument-hint: --add|-a "what broke", --list|-l, --show|-s <id>, --insight|-i <id>
+---
+
+Manage the fix log in `.scrumrun/fixes.md`: $ARGUMENTS
+
+Each fix entry uses a stable id in the form `F-NNN` (for example `F-001`), assigned sequentially. The log tracks what went wrong and what was done — a corpus for detecting recurring problems.
+
+If no action flag is present in `$ARGUMENTS`, list the actions below and stop.
+
+Actions:
+
+- `--add` (`-a`) `"description"`: register a new fix entry with the next `F-NNN` id, stamped with today's date. Describe what broke, what was done, and optionally reference the relevant sprint or `K-NNN` knowledge entry.
+- `--list` (`-l`): list all entries, most recent first, showing the id, date, and the first line of the description. Do not modify files.
+- `--show` (`-s`) `<id>`: show the full details of a single `F-NNN` entry. Do not modify files.
+- `--insight` (`-i`) `<id>`: read this fix entry and the full fix log to detect recurring patterns. If repeated failures are found, create a pending knowledge proposal (or add an insight to an existing `K-NNN`) so the lesson becomes durable. Ask the user before creating any knowledge entry.
+
+When `/sc-sprint --fix` creates a corrective child sprint, it automatically registers an entry in `.scrumrun/fixes.md` — no manual `--add` is needed for sprint-originated fixes.
+
+Do not modify application code.

package/templates/codex/prompts/sc-goal.md

@@ -0,0 +1,14 @@
+---
+description: Manage project goal lanes — set, show, list
+argument-hint: --set <goal>, --show|-s [focus], --list|-l [filter]
+---
+
+Manage the project goal lanes under `.scrumrun/goals/`: $ARGUMENTS
+
+If no action flag is present in `$ARGUMENTS`, list the actions below and stop without guessing an action.
+
+Actions:
+
+- `--set` (`--new` and `-n` are legacy aliases) `<goal>`: plan or replace the main project goal in `.scrumrun/goals/main/sprint.md`. Read `AGENTS.md`, `.scrumrun/golden-rules.md`, `.scrumrun/config.md`, `.scrumrun/map.md`, `.scrumrun/project.md`, `.scrumrun/knowledge.md`, `.scrumrun/agents.md`, and `.scrumrun/goals/main/history.md`. Use only `Approved Knowledge` as planning truth. If `.scrumrun/config.md` says `Sprint Automation: backlog` or `bypass`, treat suggested sprints as backlog candidates and do not generate, modify, or run sprint plans automatically unless the user explicitly requests `/sc-sprint --add` or `/sc-backlog --add`. Ask all blocking architecture and stack questions before writing the plan, then update `.scrumrun/project.md`, `.scrumrun/goals/main/sprint.md`, and `.scrumrun/goals/main/decisions.md` as needed.
+- `--show` (`-s`) `[focus]`: read `.scrumrun/project.md`, `.scrumrun/goals/main/sprint.md`, `.scrumrun/goals/main/history.md`, and `.scrumrun/goals/main/decisions.md`, and show the main goal status, next sprint, blockers, and open decisions. Do not modify files.
+- `--list` (`-l`) `[filter]`: list goal lanes under `.scrumrun/goals/`, including each lane's sprint and history status. The default lane is `main`. Do not modify files.

package/templates/codex/prompts/sc-golden.md

@@ -0,0 +1,14 @@
+---
+description: Manage golden rules — absolute priority, never violated
+argument-hint: --add|-a <rule>, --list|-l, --remove|-r <number>
+---
+
+Manage golden rules in `.scrumrun/golden-rules.md`; they have absolute priority and are never violated: $ARGUMENTS
+
+If no action flag is present in `$ARGUMENTS`, list the actions below and stop without guessing an action.
+
+Actions:
+
+- `--add` (`-a`) `<rule>`: append a new numbered golden rule to `.scrumrun/golden-rules.md` (create the file if missing) and show the updated list.
+- `--list` (`-l`): read and list the golden rules. Do not modify files.
+- `--remove` (`-r`) `<number>`: remove rule N from `.scrumrun/golden-rules.md` and show the updated list.

package/templates/codex/prompts/sc-help.md

@@ -0,0 +1,12 @@
+---
+description: Show ScrumRun commands grouped by workflow
+argument-hint: optional command or topic
+---
+
+Show ScrumRun help for the current project.
+
+Read `.scrumrun/config.md` if it exists to honor the response language. Explain commands by category: project, study/challenge intake, local vault, knowledge, context economy, config, golden rules, map, goals, sprint automation, features, sprints, agents, reviews, decisions, and CLI maintenance.
+
+If a command or topic is provided, focus on that topic and include examples.
+
+Topic: $ARGUMENTS

package/templates/codex/prompts/sc-init.md

@@ -0,0 +1,14 @@
+---
+description: Initialize ScrumRun project files locally by default
+argument-hint: optional --local|-l, --shared|-s, --no-agent-hint|-n, or project goal/context
+---
+
+Initialize the project with ScrumRun control files.
+
+By default, recommend `scrumrun init` for existing projects. It behaves like `scrumrun init --local` (`-l`): create `AGENTS.md` and `.scrumrun/`, add both to `.git/info/exclude`, and keep ScrumRun out of commits. Use `--no-agent-hint` (`-n`) to skip `AGENTS.md`.
+
+For teams that want ScrumRun committed, use `scrumrun init --shared` (`-s`).
+
+If files already exist, ask before overwriting.
+
+Project goal or options: $ARGUMENTS

package/templates/codex/prompts/sc-intake.md

@@ -0,0 +1,22 @@
+---
+description: Route a natural-language request through ScrumRun and ask before acting
+argument-hint: problem, desired change, or idea
+---
+
+Run ScrumRun natural-language intake for: $ARGUMENTS
+
+Read `AGENTS.md`, `.scrumrun/core.md`, `.scrumrun/golden-rules.md`, `.scrumrun/config.md`, `.scrumrun/token-policy.md`, `.scrumrun/context.md`, `.scrumrun/map.md`, `.scrumrun/project.md`, `.scrumrun/knowledge.md`, and only the backlog, plans, history, decisions, feature files, and source areas relevant to classifying this request. Relevant history is mandatory. Use only approved knowledge as planning truth.
+
+Determine the desired outcome, urgency, scope, risk, uncertainty, and relationship to the main goal. Route the request to exactly one recommended workflow:
+
+- quick task;
+- knowledge or discovery;
+- main-goal sprint;
+- corrective fix linked to prior work;
+- backlog candidate;
+- isolated feature lane;
+- reject or defer.
+
+Follow `Interaction Mode`, `Execution Approval`, and `Quick Tasks` from `.scrumrun/config.md`. In guided mode, return the classification, recommendation with rationale, important evidence, material risks or unknowns, and at most two useful alternatives. Ask one clear approval question when required; otherwise state which configured policy authorizes the next transition.
+
+Intake is read-only. Do not create or update planning records, modify application code, run tests as implementation verification, execute a sprint, or interpret an ambiguous acknowledgement as approval. After explicit approval, invoke the matching canonical workflow using `--add`, `--set`, `--update`, `--remove`, `--run`, `--audit`, `--approve`, or `--reject` as appropriate.

package/templates/codex/prompts/sc-know.md

@@ -0,0 +1,75 @@
+---
+description: Add, approve, reject, update, rename, annotate, remove, show, or list project knowledge
+argument-hint: --add <topic>, --approve <id>, --reject <id>, --update <id>, --rename <id> "title", --insight <id> <text>, --remove <id>, --show [id], --list
+---
+
+Manage ScrumRun project knowledge in `.scrumrun/knowledge.md`: $ARGUMENTS
+
+Read `.scrumrun/golden-rules.md`, `.scrumrun/config.md`, `.scrumrun/map.md`, `.scrumrun/project.md`, `.scrumrun/knowledge.md`, `.scrumrun/goals/main/history.md`, feature histories when relevant, and source files needed to verify the topic.
+
+Identifiers:
+
+- Each knowledge entry uses a stable id in the form `K-NNN` (for example `K-001`), assigned sequentially.
+
+Flags (may be combined):
+
+- `--add`: investigate a topic and create a pending proposal. A bare topic is a legacy alias.
+- `--approve`: approve one pending proposal with explicit owner consent. Positional `approve` is a legacy alias.
+- `--reject`: reject one pending proposal. Positional `reject` is a legacy alias.
+- `--deep` (`-d`): study the topic deeply and add a code map (see below).
+- `--update` (`--edit`, `-e` legacy aliases): rewrite an existing `K-NNN` entry; see edit mode.
+- `--rename` (`-rn`): change only the title of an existing `K-NNN` entry; the id never changes.
+- `--insight` (`-i`): append a dated reasoning to an existing `K-NNN` entry without rewriting it.
+- `--remove` (`-r`, or `--delete`): delete an existing `K-NNN` entry.
+- `--show` (`--resume`, `-s` legacy aliases): render knowledge as a clean, readable summary; read-only.
+
+Modes:
+
+1. `list`: show approved knowledge, pending proposals, and rejected proposals. Do not modify files.
+2. `approve <id>`: move a pending proposal into `Approved Knowledge` only if the user's approval is explicit. Preserve source references, caveats, date, and approver.
+3. `reject <id>`: move a pending proposal into `Rejected Proposals` with the reason when provided.
+4. `remove <id>` or `<id> --remove`: delete that `K-NNN` entry from whichever section it is in, and report what was removed.
+5. `<id> --edit [text]`: recreate the existing `K-NNN` entry under the same id. If text is supplied, use it as the new basis. If no text is supplied, reuse the entry's current title and insight and re-investigate from source. Combine with `--deep` to rewrite it deeply. The rewritten entry becomes a pending proposal under the same id and must be re-approved.
+6. `<id> --rename "new title"`: change only the title of that `K-NNN` entry. The id never changes, and verified facts, code map, status, insights, date, and approver are all preserved. Mention the previous title in the change.
+7. `<id> --insight <text>`: append a new dated insight — a reasoning, observation, or hypothesis — to that `K-NNN` entry under an `Insights` log, without changing its verified facts, code map, or status. Insights accumulate: never overwrite earlier ones, and mark them as insights, not verified facts. Create the `Insights` section if it does not exist yet.
+8. `<id> --resume` or `--resume` (`-s`): render knowledge as a clean, readable summary instead of raw markdown. With a `K-NNN` id, present that single entry; with no id, present an organized overview of the whole base. Read-only — do not modify files. See the resume output format below.
+9. any other text: investigate the topic and create a new pending knowledge proposal with the next `K-NNN` id. Do not put it directly into `Approved Knowledge`. With `--deep`, also build a code map.
+
+For a new or rewritten pending proposal, include:
+
+1. stable id in `K-NNN` form;
+2. title;
+3. user insight, if supplied;
+4. verified facts with file references;
+5. assumptions and uncertainty;
+6. risks if this knowledge is wrong;
+7. affected modules;
+8. suggested use in future challenges or sprints;
+9. approval prompt;
+10. code map, only when `--deep` is used: key functions or symbols with `file:line` or `file:start-end` references, the main entry points and call sites, and the relevant types, config, or storage touchpoints. Short signatures or excerpts are allowed when they clarify behavior. Treat function and symbol names as the stable anchor and line numbers as point-in-time for the proposal date.
+
+Resume output (`--resume`):
+
+Render a scannable digest, not the raw file. For a single `K-NNN` entry, use clear sections:
+
+- a heading line with the id, title, and a status label (Approved, Pending, or Rejected);
+- **What it is**: one or two plain-language sentences;
+- **Key facts**: bullets, each with its `file:line` reference;
+- **Affected modules**: a short list;
+- **Code map**: only if the entry has one — functions or symbols with `file:line`, entry points, and call sites;
+- **Assumptions & risks**: brief bullets;
+- **Suggested use**: where this should inform challenges or sprints;
+- a compact footer with status, date, and approver when present.
+
+For the whole base (no id), group entries under Approved, Pending, and Rejected, and show each as a compact card — `K-NNN — Title`, a one-line summary, and its status — sorted by id. Read-only.
+
+Rules:
+
+1. Approved knowledge can influence `/sc-challenge`, `/sc-sprint --add`, `/sc-sprint --run`, and feature planning.
+2. Pending proposals are not planning truth. Mention them only as unapproved context.
+3. Rejected proposals must not be used for planning except to avoid repeating a known bad assumption.
+4. Editing an approved entry returns it to pending for re-approval; never silently keep edited content as approved.
+5. Insights are additive, dated annotations: advisory context, not verified planning truth. Adding an insight never rewrites the entry or changes its status. If an insight should become verified knowledge, use `--edit`.
+6. Renaming changes only an entry's title; the `K-NNN` id is permanent and must never change.
+7. Do not change application code.
+8. Do not create sprints, backlog items, feature lanes, or history entries unless the user explicitly asks with another command.

package/templates/codex/prompts/sc-map.md

@@ -0,0 +1,13 @@
+---
+description: Manage the project map — build, view
+argument-hint: --build|-b, --view|-v
+---
+
+Manage the project map in `.scrumrun/map.md`: $ARGUMENTS
+
+If no action flag is present in `$ARGUMENTS`, list the actions below and stop without guessing an action.
+
+Actions:
+
+- `--build` (`-b`): build or refresh `.scrumrun/map.md` with the project structure, important paths, modules, and key files. Do not include secrets.
+- `--view` (`-v`): show a concise project structure view using `.scrumrun/map.md` and current folders without modifying files.

package/templates/codex/prompts/sc-review.md

@@ -0,0 +1,13 @@
+---
+description: Run a ScrumRun review — full codebase or a single file range
+argument-hint: --code|-c [focus], --file|-f <path:start_end>
+---
+
+Run a ScrumRun review: $ARGUMENTS
+
+If no action flag is present in `$ARGUMENTS`, list the actions below and stop without guessing an action.
+
+Actions:
+
+- `--code` (`-c`) `[focus]`: review the full codebase and save a timestamped report under `.scrumrun/reviews/`. Order findings by severity with file and line references. Do not modify code unless explicitly requested.
+- `--file` (`-f`) `<path:start_end>`: review the requested file range only, without changing code unless explicitly asked.

package/templates/codex/prompts/sc-sprint.md

@@ -0,0 +1,28 @@
+---
+description: Manage main-goal sprints — add, list, status, show, rename, run, audit, fix, discuss, bypass, commit-message
+argument-hint: --add [* name], --list|-l, --status|-st [id], --show|-s <id>, --rename|-rn <id> "name", --run|-r [--backlog|-k] <id>, --audit|-a <id>, --fix|-f <id>, --discuss|-d <id>, --bypass|-b, --commit-message|-cm <id>
+---
+
+Manage main-goal sprints in `.scrumrun/goals/main/`: $ARGUMENTS
+
+If no action flag is present in `$ARGUMENTS`, list the actions below and stop without guessing an action.
+
+Before any planning or execution action, read `.scrumrun/knowledge.md` and use only `Approved Knowledge` as planning truth.
+
+Important: `.scrumrun/goals/main/sprint.md` is the planned catalog — it lists what *should* happen. `.scrumrun/goals/main/history.md` is the executed truth — it records what *did* happen. Sprint execution status (completed, partial, blocked, pending) is determined solely from `history.md`. Never infer status from `sprint.md` alone. Every status query (`--list`, `--status`, `--show`) must cross-reference both files; neither is sufficient on its own.
+
+Actions:
+
+- `--add` (`--new` and `-n` are legacy aliases) `[*] <name>`: create a new sprint in `.scrumrun/goals/main/sprint.md`; prefix the name with `*` to mark priority. Read `.scrumrun/golden-rules.md`, `.scrumrun/config.md`, `.scrumrun/knowledge.md`, `.scrumrun/goals/main/sprint.md`, and `.scrumrun/goals/main/history.md` first. Assign the next available sprint number and add goal, scope, acceptance criteria, dependencies, and suggested verification.
+- `--list` (`-l`): cross-reference `.scrumrun/goals/main/sprint.md` and `.scrumrun/goals/main/history.md` now — never assume status from sprint.md alone. Show current sprint status (completed, pending, blocked, next steps) as recorded in history.md. Do not use cached context. Do not modify files.
+- `--status` (`-st`) `[id]`: cross-reference `.scrumrun/goals/main/sprint.md` and `.scrumrun/goals/main/history.md` now — status comes from history.md, not sprint.md. Output only a compact Markdown table with exactly three columns: `Sprint | Breve descricao | Status`. If `[id]` is present, show only that sprint; otherwise show one row per sprint. Keep descriptions brief, derived from the sprint title or goal. Use status labels with emojis: `✅ feito` for completed, `🚧 parcial` for partial, `⛔ bloqueado` for blocked, and `⏳ pendente` when no history entry exists. Do not add narrative before or after the table. Do not modify files.
+- `--show` (`-s`) `<id>`: cross-reference both sprint.md and history.md now and show the requested sprint with a clear non-technical Goal first, plus scope, acceptance, and its history entry (the executed truth).
+- `--rename` (`-rn`) `<id> "new name"`: change only the sprint's descriptive label in `.scrumrun/goals/main/sprint.md`; keep its number/id unchanged, since history and backlog reference the number. Note the change in `.scrumrun/goals/main/history.md` as "renamed from X to Y". Do not modify application code.
+- `--run` (`-r`) `<id>`: execute the requested sprint with history check, the ScrumRun protocol, and handoff. If `$ARGUMENTS` also includes `--backlog` (`-k`) or `--to-backlog`, do not execute: add the sprint candidate to `.scrumrun/backlog.md`, report the entry, and stop.
+- `--audit` (`-a`) `<id>`: read `.scrumrun/goals/main/sprint.md`, `.scrumrun/goals/main/history.md`, and the sprint's changed files now, then audit from current file state. Do not use cached context.
+- `--fix` (`-f`) `<id>`: corrective pass on a sprint that went wrong. First ask the user what went wrong and wait for the answer — do not guess. Then propose an executable corrective child sprint and, once the user confirms, create it as `Sprint <id>.M` (a dotted child such as `02.1`, then `02.2`) in `.scrumrun/goals/main/sprint.md`: derive its goal, scope, and acceptance from the problem and link it to parent `<id>`. Leave the parent sprint's recorded plan intact and mark it as patched by the child. Record what happened in `.scrumrun/goals/main/history.md`, capture the lesson in `.scrumrun/knowledge.md` (a pending proposal, or an insight on the relevant `K-NNN` entry — never auto-approved; ask the user to approve it), and log any decision or risk in `.scrumrun/goals/main/decisions.md`. The fix is run later with `/sc-sprint --run <id>.M`. A fix that itself needs fixing becomes a sibling (`<id>.M+1`), not a deeper nest. Also register the fix in `.scrumrun/fixes.md` as `F-NNN` linked to both `<id>` and `<id>.M`. Do not change application code.
+- `--commit-message` (`-cm`) `<id>`: return a single, succinct commit message summarizing what that sprint delivered. Read `.scrumrun/goals/main/sprint.md` and `.scrumrun/goals/main/history.md`, plus the sprint's changed files when helpful. Output only the message: one line, imperative mood, lowercase, no trailing period, and as few characters as possible while staying clear. Do not stage, commit, or modify any files.
+- `--discuss` (`-d`) `<id>`: read the sprint and history, discuss the user's concern about the approach, and explore better paths.
+- `--bypass` (`-b`) `[context]`: set `.scrumrun/config.md` to `Sprint Automation: backlog` for legacy or hand-managed projects, so suggested sprints are treated as backlog candidates until the user chooses what to run. Keep other preferences intact, note the change in `.scrumrun/project.md` or `.scrumrun/goals/main/decisions.md`, and prefer `/sc-backlog --add` and `/sc-backlog --list` for candidate management.
+
+Do not modify application code.

package/templates/codex/prompts/sc-study.md

@@ -0,0 +1,23 @@
+---
+description: Deep-study the project — stack, architecture, permissions, risks, and backlog candidates
+argument-hint: optional focus area
+---
+
+Run a deep ScrumRun study of the project and produce a complete operational understanding. Do not modify files: $ARGUMENTS
+
+Read ScrumRun control files first, then inspect the repository deeply enough to understand:
+
+1. product purpose and active goals;
+2. stack, frameworks, package managers, runtime versions, and local commands;
+3. architecture, entry points, routing, controllers, services, jobs, and important modules;
+4. auth, authorization, roles, permissions, policies, guards, and access boundaries;
+5. data model, migrations, seeds, storage, queues, caches, and external state;
+6. env/config requirements, secret handling, third-party integrations, and webhooks;
+7. deployment/infrastructure clues, CI, test strategy, and observability;
+8. legacy risks, security concerns, performance hotspots, brittle areas, and unknowns;
+9. current sprint plan, history, decisions, feature lanes, review agents, and backlog.
+10. approved knowledge, pending knowledge proposals, and rejected assumptions from `.scrumrun/knowledge.md`.
+
+Prefer precise file references over generic statements. If an area cannot be verified from the repo, say it is unknown and explain what evidence is missing.
+
+When recommending sprints, present them as backlog candidates. Do not create, run, or mark sprints unless the user explicitly asks for `/sc-sprint --add`, `/sc-backlog --add`, or `/sc-sprint --run`.

package/templates/codex/prompts/sc-uninstall.md

@@ -0,0 +1,14 @@
+---
+description: Remove ScrumRun from the current project
+argument-hint: optional --force|-f
+---
+
+Remove ScrumRun from the current project.
+
+Default behavior is conservative: remove ScrumRun entries from `.git/info/exclude` and show what would be removed.
+
+With `--force` (`-f`), remove `.scrumrun/` and remove `AGENTS.md` only if it is recognized as ScrumRun-generated.
+
+Do not remove application code or unrelated project files.
+
+Options: $ARGUMENTS

package/templates/codex/prompts/sc-update.md

@@ -0,0 +1,6 @@
+---
+description: Update installed ScrumRun commands and skill to latest version
+argument-hint: optional target: all, codex, opencode, or claude
+---
+
+Update installed ScrumRun commands and skill to the latest version: $ARGUMENTS

package/templates/codex/prompts/sc-vault.md

@@ -0,0 +1,27 @@
+---
+description: Manage local development secrets in .scrumrun/vault.local.md
+argument-hint: --add|-a <name:value>, --list|-l, --show|-s <name>, --remove|-r <name>
+---
+
+Manage the local development vault in `.scrumrun/vault.local.md`: $ARGUMENTS
+
+This vault is for development-only credentials and local test values. It is plaintext Markdown, not encrypted storage, and must never be committed or used for production secrets.
+
+Rules:
+
+1. Store values only in `.scrumrun/vault.local.md`.
+2. Ensure `.scrumrun/vault.local.md` is listed in `.git/info/exclude` when the project is a Git repository.
+3. Never copy vault values into sprint history, backlog, knowledge, reviews, decisions, commits, logs, or normal answers.
+4. For `--list`, show ids/names only and redact values.
+5. For `--show`, reveal only the explicitly requested local value.
+6. For `--add`, accept either `<name:value>`, `<name=value>`, or `<name> <value>`.
+7. For `--remove`, delete the requested entry.
+8. Do not modify application code.
+
+Actions:
+
+- `--add` (`-a`) `<name:value>`: add or append a local development secret.
+- `--list` (`-l`): list local vault entries with values redacted.
+- `--show` (`-s`) `<id|name>`: show one local value.
+- `--remove` (`-r`) `<id|name>`: remove one local value.
+- `--path`: show the vault file path.