Happy coding! Build something awesome.
Drop-in template repo that implements a structured its-magic workflow in Cursor: intake -> discovery -> architecture -> sprint plan -> execute -> QA -> release, with pause/resume, decision gates, and persistent artifacts.
decisions/DEC-xxxx.md).handoffs/resume_brief.md).US-0071 / DEC-0053):
python scripts/check-user-visible-metadata.py (see docs/engineering/runbook.md).docs/engineering/runbook.md.scratchpad.local.md).its-magic is an installer you run once per repo. It copies the AI dev team
workflow files (.cursor/ commands, rules, agents, hooks, skills, plus docs/,
sprints/, handoffs/, etc.) into your project.
Starter artifacts are shipped as clean placeholders (no preloaded sprint/demo
history), so /intake starts from your own idea.
Pick one method:
| Method | Install command |
|---|---|
| npm | npm install -g its-magic |
| npx | npx its-magic --target . --mode missing |
| Chocolatey | choco install its-magic (Admin shell) |
| Homebrew | brew tap USER/tap && brew install its-magic |
New repo:
mkdir my-project && cd my-project
git init
its-magic --target . --mode missing --create
Existing repo (safe merge):
its-magic --target . --mode missing
Existing repo (overwrite + backup):
its-magic --target . --mode overwrite --backup
When you update its-magic to a newer version (npm update -g its-magic), run
upgrade mode to update framework files while preserving your project data:
its-magic --target . --mode upgrade
What upgrade does:
README.md) are preserved. If the template version has new
content, a review notice is printed..cursor/scratchpad.md
is not copied as a manifest file; the installer materializes it from the
packaged template when missing and validates required merged keys (Python
required). Legacy repos that already committed .cursor/scratchpad.md keep it on
upgrade (not overwritten).its_magic/.its-magic-version in your repo.TEST_COMMAND, optional LINT_COMMAND/TYPECHECK_COMMAND) and preserves
explicit user overrides.Upgrade with backup (backs up framework files before updating):
its-magic --target . --mode upgrade --backup
/intake with your idea# Show banner + help
its-magic
# Show version only
its-magic --version
# Install workflow files into current repo
its-magic --target . --mode missing
# Clean previously installed workflow artifacts
its-magic --clean-repo --target .
Install options
| Flag | Description |
|---|---|
--target <path> | Path to the repository where workflow files are installed. If omitted you are prompted interactively. |
--mode missing | Default. Only copy files that do not exist yet. Safe for repos that already have some workflow files. |
--mode overwrite | Replace every file, even if it already exists. Combine with --backup to keep a snapshot first. |
--mode interactive | Ask per file whether to overwrite or skip. Useful when you want to cherry-pick updates. |
--mode upgrade | Update framework files (commands, rules, agents, hooks, skills, CI, scripts) while preserving user data (docs, sprints, handoffs, decisions). Use after updating its-magic to a newer version. |
--backup | Before overwriting, save existing files to backups/<timestamp>/. Ignored in missing mode (nothing gets replaced). |
--create | Create the target directory if it does not exist. |
Clean options
| Flag | Description |
|---|---|
--clean-repo | Remove installer-owned its-magic workflow artifacts from the target repo (manifest-owned paths including .cursor, docs/product, docs/engineering, docs/user-guides, sprints, handoffs, decisions, workflow scripts, CI files, installer metadata in its_magic/, and legacy .its-magic-version). Your own source code is never touched. |
--yes | Skip the confirmation prompt when cleaning. |
Info
| Flag | Description |
|---|---|
--help, -h | Show banner, version, repo URL, and full usage reference. |
--version, -v | Print the installed its-magic version and exit. |
its-magic lifecycle behavior is validated in both installer and CLI paths.
Primary coverage:
| Scenario | Local coverage | CI coverage | Expected evidence |
|---|---|---|---|
Fresh install (missing) | tests/run-tests.ps1, tests/run-tests.sh | npm/brew/choco jobs | Required files + its_magic/.its-magic-version |
| Overwrite + backup | tests/run-tests.ps1, tests/run-tests.sh | lifecycle subset in CI jobs | Backup snapshot contains overwritten framework file |
| Upgrade lifecycle | tests/run-tests.ps1, tests/run-tests.sh, npm local package tests | lifecycle subset in CI jobs | Framework file restored, user-data preserved |
| Clean-repo safety | tests/run-tests.ps1, tests/run-tests.sh, npm local package tests | lifecycle subset in CI jobs | Framework artifacts removed, non-framework marker preserved |
| Negative-path invalid mode/args | tests/run-tests.ps1, tests/run-tests.sh | lifecycle subset in CI jobs | Non-zero fail-fast behavior |
Run locally:
sh tests/run-tests.sh
powershell -ExecutionPolicy Bypass -File tests/run-tests.ps1
/<command> + 1-3 lines context./pause, /resume, /refresh-context) command-only is fine.your-project/
.cursor/commands/ Cursor slash commands
.cursor/rules/ AI behavior rules
.cursor/agents/ Subagent definitions
.cursor/skills/ Reusable skills
.cursor/hooks/ Automation hooks
.cursor/scratchpad.md Materialized shared defaults (Model B; not manifest-copied)
.cursor/scratchpad.local.example.md Framework default key catalog
docs/ Engineering & product docs, runbook
sprints/ Sprint tracking artifacts
handoffs/ Phase handoff artifacts
decisions/ Decision records
scripts/validate-and-push.ps1 Local test-fix-push loop (Windows)
scripts/validate-and-push.sh Local test-fix-push loop (Linux/Mac)
.github/workflows/ CI with auto-fix loop
README.md
Use three layers (merge precedence: local > materialized baseline > example,
DEC-0055):
.cursor/scratchpad.local.example.md (installed; refreshed on upgrade).cursor/scratchpad.md (materialized on install when missing; commit as you prefer).cursor/scratchpad.local.md (gitignored; never overwritten by install/upgrade)Setup:
its-magic — baseline is materialized and merged validation runs (requires Python on PATH for installer.ps1 / installer.sh)..cursor/scratchpad.local.example.md to .cursor/scratchpad.local.md for personal values (TEAM_MEMBER, ACTIVE_TASK_IDS, …).Recovery if .cursor/scratchpad.md is missing or merge validation fails:
python installer.py --scratchpad-postinstall --target . --mode missing
Upgrade behavior (US-0057 / DEC-0057):
Aligns with DEC-0039 (example vs local ownership), DEC-0057 (example-first ordering relative to baseline materialization), and Model B baseline rules below.
.cursor/scratchpad.local.example.md is framework-owned and always refreshed from
the shipped template during post-install before baseline handling (DEC-0057 AC-1..AC-3).
.cursor/scratchpad.local.md is user-owned and preserved on --mode upgrade.
Existing .cursor/scratchpad.md is left untouched on upgrade unless missing (then
materialized) or overwrite / fresh materialize paths apply (Model B).
Installer output uses [SCRATCHPAD_LAYER] lines to distinguish example refresh,
baseline materialize/skip, and user-local preservation (DEC-0057 AC-5).
Paired catalog parity (baseline vs .cursor/scratchpad.local.example.md, active and
template/): python scripts/check-scratchpad-pair-parity.py --repo . (wired into
tests/run-tests.ps1 / tests/run-tests.sh; AC-11).
Deterministic ordering behavior (US-0058):
docs/engineering/artifact-ordering-policy.md.state.md checkpoints are append-bottom; backlog.md and acceptance.md
remain sorted-canonical by story ID.ARTIFACT_ORDERING_ANCHOR_AMBIGUOUS.STATE_TIMESTAMP_NON_MONOTONIC.Intake runtime safety behavior (US-0059):
/intake requires role-specific po capability by default and fails fast with
SUBAGENT_CAPABILITY_UNAVAILABLE when unavailable.INTAKE_SUBAGENT_FALLBACK=allow.INTAKE_CONCURRENT_WRITER_DETECTED.Runtime QA autopilot behavior (US-0065):
startup -> readiness/connectivity -> log scan -> bounded retry -> verdict.RUNTIME_STARTUP_FAILED, RUNTIME_ENDPOINT_UNREACHABLE,
RUNTIME_LOG_CRITICAL_DETECTED, RUNTIME_RETRY_BUDGET_EXHAUSTED,
RUNTIME_STACK_PROFILE_UNRESOLVED.local|remote), health result, retry ledger, and log severity summary.Generated test scaffolding + auto-run behavior (US-0066):
/execute resolves stack profile (node|python|go|java|dotnet) and generates
missing baseline unit/integration/acceptance tests only.TEST_COMMAND wiring is deterministic:
/qa automatically runs the generated baseline tests and records deterministic
evidence (command, result, output ref, generated paths ref).TEST_SCAFFOLD_STACK_UNRESOLVED,
TEST_SCAFFOLD_UNSUPPORTED_STACK,
TEST_SCAFFOLD_GENERATION_FAILED./ask: ask questions using project context (read-only, no artifacts created)./intake: capture idea, backlog, acceptance./discovery: collect UX/product references./research: risks, patterns, dependencies./architecture: technical approach and decisions./sprint-plan: sprint and task list./plan-verify: acceptance coverage check./execute: implement tasks./qa: test and report findings./verify-work: UAT./release: release notes + runbook updates./memory-audit: read-only memory drift check with advisory report./pause, /resume, /refresh-context./auto: orchestration mode that spawns a fresh subagent per phase./intake supports two PO interaction modes via .cursor/scratchpad.md:
INTAKE_GUIDED_MODE=1 (default)
INTAKE_GUIDED_MODE=0 (low-touch)
When guided mode is enabled, /intake now supports bounded decomposition for
broad/high-risk requests:
INTAKE_GUIDED_MODE=0 unless explicitly requesteddocs/product/backlog.md, docs/product/acceptance.md,
handoffs/po_to_tl.md)/intake now enforces deterministic minimum questionnaire packs before
backlog/acceptance persistence:
first-intake-pack for first/new/broad requestssmall-intake-pack for narrow follow-up requestsFail-closed coverage behavior:
first-intake-packDeterministic reason codes:
INTAKE_REQUIRED_TOPIC_MISSINGINTAKE_REQUIRED_PACK_INCOMPLETEINTAKE_ASSUMPTION_CONFIRMATION_REQUIREDINTAKE_PERSISTENCE_BLOCKEDIntake artifacts must persist coverage evidence fields:
asked_topicsmissing_topicsassumptions_confirmedUS-0078 closes silent persistence: every intake that mutates backlog/acceptance must pass the
deterministic intake_evidence gate — topic_coverage with valid ie: refs,
asked-vs-covered alignment, and assumption_confirmation_ref when assumptions are affirmative.
python scripts/intake_evidence_validate.py --self-test (also exercised via tests/run-tests.* §26k).intake_evidence_validate.py, intake_evidence_lib.py, intake_bug_routing_guard.py) ship under template/scripts/ and hydrate consumer repos at scripts/ (npm files, Chocolatey/Homebrew template/ tree, installer.ps1 / installer.sh + installer-owned-paths.manifest). --mode upgrade treats them as framework files (added/updated like other shipped scripts). CI parity: python scripts/check_intake_template_parity.py --repo . (tests/run-tests.* §26N).decisions/DEC-0060.md, docs/engineering/architecture.md # US-0078, runbook section Interactive intake evidence validation (US-0078 / DEC-0060).Defects use BUG-#### under docs/product/backlog.md ## Bug issues (canonical) with OPEN/DONE only and minimum reproducibility fields. Intake must not silently file defect prose as US-xxxx: set merged scratchpad INTAKE_WORK_ITEM_KIND=bug and/or use /intake bug, then run python scripts/intake_bug_routing_guard.py --kind story --file <prose.txt> before story allocation when in doubt.
python scripts/bug_issue_validate.py --self-test; python scripts/bug_issue_validate.py --backlog docs/product/backlog.md --check-acceptance.decisions/DEC-0061.md, docs/engineering/architecture.md # US-0079, runbook Bug issues (US-0079 / DEC-0061).Fresh-project ID bootstrap behavior is explicit and default-off:
ID_NAMESPACE_BOOTSTRAP=0|1 in .cursor/scratchpad.md (default 0)When enabled (1), workflows use deterministic freshness checks before first ID
creation:
US- IDs in docs/product/backlog.mdDEC- IDs in docs/engineering/decisions.md / decisions/DEC-*.mdR- IDs in docs/engineering/research.mdIf eligible, first IDs start at US-0001, DEC-0001, and R-0001. If not
eligible (or mode is off), generation continues from highest existing IDs.
Historical IDs are never rewritten or renumbered. Ineligible bootstrap requests
emit deterministic diagnostic ID_BOOTSTRAP_NOT_FRESH.
Token-cost behavior is controlled by .cursor/scratchpad.md:
TOKEN_PROFILE=lean|balanced|full (default balanced)Profile behavior:
lean: reduce non-critical overhead defaults (automation/research/context
breadth) while keeping mandatory quality gates intact.balanced: preserve current capabilities with moderate overhead.full: maximize context breadth/autonomy for high-uncertainty work.Manual override precedence:
/qa -> /verify-work -> /release
gate semantics.Compaction behavior:
docs/engineering/state.md is the active hot surface.docs/engineering/state-archive/.docs/engineering/decisions.md stays a compact index with bounded summaries
and canonical links to decisions/DEC-xxxx.md.STATE_HOT_MAX_LINES (default 1200)STATE_HOT_MAX_CHECKPOINTS (default 80)PO_TO_TL_HOT_MAX_LINES (default 800)PO_TO_TL_HOT_MAX_SECTIONS (default 60)ARCH_HOT_MAX_LINES (default 3500)ARCH_HOT_MAX_STORY_SECTIONS (default 120)
Triad hot surfaces (state.md, handoffs/po_to_tl.md,
docs/engineering/architecture.md) must stay within merged scratchpad caps./auto phase spawn (see .cursor/commands/auto.md)./auto start-from=<phase> when resuming so resolved_phase_plan
intersection stays deterministic (DEC-0052).TOKEN_PROFILE=lean when compatible with your work to reduce scratchpad-driven
breadth; mandatory gates (US-0048, US-0056, US-0069, US-0039) stay on.run_class_hash; otherwise
TOKEN_COST_RUN_CLASS_MISMATCH (no cross-plan gaming).handoffs/token_cost_runs/<orchestrator_run_id>.md; link from
docs/engineering/state.md via token_cost_evidence_ref.scripts/token_cost_lib.py, scripts/token_cost_compare.py,
python scripts/check_token_cost_parity.py --repo ..
Use python scripts/enforce-triad-hot-surface.py --check before completing a
phase that mutates them; use --rollover to archive oldest material into
deterministic packs when over cap (DEC-0054).
Archive verification mismatch fails with
STATE_ARCHIVE_VERIFICATION_FAILED.To prevent accidental history loss across workflow phases:
docs/engineering/artifact-ownership-policy.mddocs/engineering/architecture.md is history-preserving (append or
target-section-only mutation)PHASE_OWNERSHIP_VIOLATION,
PHASE_OVERRIDE_EVIDENCE_MISSING,
ARCH_HISTORY_DELETION_DETECTED/ask policy (read-only):
Post-release publish behavior is configurable per repository:
RELEASE_PUBLISH_MODE=disabled|confirm|auto (default confirm)RELEASE_TARGETS_FILE=docs/engineering/release-targets.jsonRELEASE_TARGETS_DEFAULT= optional comma-separated default targetsSupported target types include:
npm, choco, brew, git, docker, cloudcustom (generic command target)ssh (generic server deployment over SSH)runtime.mode (local|remote)domainEnv|ipEnv|hostEnv, port, protocol)dockerOverSsh contract for remote Docker execution over SSHSafety defaults:
/release gates are unchanged and must pass first.confirm mode enforces explicit operator approval before publish execution.tokenEnv, authEnv), not
inline literals.REMOTE_CONNECTIVITY_CONFIG_INVALID.docs/engineering/runtime-connectivity.md.Use /status-reconcile to normalize status drift between canonical and derived
workflow artifacts before continuation:
docs/product/backlog.md story statusdocs/product/acceptance.md, docs/engineering/state.md,
handoffs/resume_brief.mddocs/engineering/status-normalization-report.mdThis command is the bounded repair counterpart to /memory-audit
(read-only detection).
Use optional compatibility visibility with default-safe off behavior:
CROSS_REPO_OBSERVABILITY=0|1 (default 0)COMPATIBILITY_GATE_ON_CRITICAL=0|1 (default 1)COMPATIBILITY_SOURCES= monitored repo/module/contract/docs declarationsWhen disabled (0), workflow adds zero required compatibility overhead.
When enabled (1), compatibility signals/findings are tracked in:
docs/engineering/compatibility-signals.mddocs/engineering/compatibility-report.mddocs/engineering/manifests/registry.manifest.yamldocs/engineering/manifests/repo.manifest.yamlIf unresolved critical findings remain and
COMPATIBILITY_GATE_ON_CRITICAL=1, release progression must stop for a
decision gate (COMPATIBILITY_CRITICAL_OPEN).
Enable scoped workflow behavior with:
COMPONENT_SCOPE_MODE=0|1 (default 0)TARGET_COMPONENTS=<comma-separated-component-ids>When disabled (0), workflow adds zero required scope overhead.
When enabled (1):
docs/engineering/component-scope.md.docs/engineering/component-scope-report.md.COMPONENT_SCOPE_VIOLATION_UNAPPROVED).Optional Design Concept, CRS, and Technical Specification artifacts are controlled by:
SPEC_PACK_MODE=0|1 (default 0)When disabled (0), intake/architecture/execute/qa/release add no required
spec-pack steps (zero overhead).
When enabled (1):
docs/engineering/spec-pack/<story_id>-design-concept.md,
docs/engineering/spec-pack/<story_id>-crs.md,
docs/engineering/spec-pack/<story_id>-technical-specification.md.docs/engineering/runbook.md.SPEC_PACK_INCOMPLETE when
required sections are missing.Optional per-feature user guides (end-user how-to docs) are controlled by:
USER_GUIDE_MODE=0|1 (default 0)When disabled (0), intake/architecture/sprint-plan/execute/qa/release add no
required user-guide steps or blocking checks (zero overhead).
When enabled (1):
docs/user-guides/US-xxxx.md.docs/engineering/runbook.md and
docs/user-guides/README.md).USER_GUIDE_INCOMPLETE
when enabled and required sections are missing.Release history is sprint-scoped and queue-backed:
handoffs/releases/Sxxxx-release-notes.mdhandoffs/release_queue.mdhandoffs/release_notes.mdDeterministic release semantics:
/release run.unreleased.released.Release gate chain (US-0039): /release enforces mandatory gates in order — check-in test, QA completion, UAT completion — then finalization. Blank optional runbook keys (LINT_COMMAND, TYPECHECK_COMMAND) do not block release; they are reported as skipped.
If a problem appears after QA (during /release), record it separately from
QA findings:
sprints/Sxxxx/release-findings.mdhandoffs/release_to_dev.mdBoundary:
sprints/Sxxxx/qa-findings.mdsprints/Sxxxx/release-findings.mdEach blocked release finding should include reason code, evidence refs, remediation, and rerun criteria.
Release completion must not leave stale backlog status for target sprint stories. At release finalization:
DONE using canonical release evidence;BACKLOG_STATUS_DRIFT if contradiction remains (e.g. released
sprint but backlog still OPEN/unchecked).docs/product/backlog.md is canonical for story OPEN|DONE status.docs/product/acceptance.md and docs/engineering/state.md are derived views
reconciled from canonical backlog status plus release evidence.docs/engineering/status-normalization-report.md.BACKLOG_STATUS_DRIFTCANONICAL_STATUS_CONFLICThandoffs/*.md + artifact
files)./auto is orchestration only: it calls phase subagents and transfers context
through artifacts.Isolation is enforced with auditable evidence written to docs/engineering/state.md.
Each phase run appends:
phase_id, role, fresh_context_marker, timestamp, evidence_refMissing/invalid/stale evidence fails closed with reason codes:
PHASE_CONTEXT_ISOLATION_MISSING, PHASE_CONTEXT_ISOLATION_VIOLATION,
ISOLATION_EVIDENCE_STALE, ISOLATION_EVIDENCE_INVALID.
Per-phase isolation also requires strict runtime attestation tuples at boundaries (not artifact fields alone):
orchestrator_run_id, runtime_proof_id, phase_id, roleproof_issued_at, proof_ttl_seconds, proof_hashFail-closed reason codes:
RUNTIME_PROOF_MISSING, RUNTIME_PROOF_INVALID, RUNTIME_PROOF_REUSED,
RUNTIME_PROOF_STALE, RUNTIME_PROOF_AMBIGUOUS_LINK.
/auto, /verify-work, and /release must validate these tuples before
continuation/finalization.
/auto phase→role enforcement (US-0069 / DEC-0051)/auto uses a deterministic phase→role matrix plus scratchpad alternates
(AUTO_ROLE_RESEARCH, AUTO_ROLE_PLAN_VERIFY, AUTO_ROLE_REFRESH_CONTEXT).
Before each phase spawn it runs a preflight capability gate; missing
capability stops with PHASE_ROLE_CAPABILITY_MISSING (no unrelated-role
substitution). After each phase, isolation role and strict-proof role must
match the same expected role or the run stops with PHASE_ROLE_MISMATCH.
execute defaults to dev; non-dev requires
AUTO_EXECUTE_ROLE_OVERRIDE=allowed_non_dev_execute and
EXECUTE_OVERRIDE_GOVERNANCE_REF pointing to a parseable approved waiver. See
docs/engineering/runbook.md and decisions/DEC-0051.md.
/auto phase selection policy (US-0070 / DEC-0052)/auto builds a resolved phase plan from scratchpad before spawning phases:
exactly one of AUTO_PHASE_PLAN (default full), AUTO_PHASE_EXCLUDE,
AUTO_PHASE_INCLUDE, or AUTO_PHASE_PROFILE applies; conflicting selectors
stop with PHASE_POLICY_CONFLICT. Non-skippable safety gates (qa,
verify-work, release) and evidence-chain closure reinstate omitted phases
with breadcrumb reasons such as non_skippable_gate. start-from and resume
anchors intersect with the plan (START_FROM_PHASE_PLAN_EMPTY_INTERSECTION
when empty). Backlog-drain, bulk execute, and team-mode runs recompute the
plan each boundary. See /auto, docs/engineering/runbook.md, and
decisions/DEC-0052.md.
Use /ask when you want to query the project without triggering the workflow:
/ask reads the project artifacts (state, backlog, architecture, decisions, sprint
progress) and answers from them. It never creates or modifies files. If your question
reveals a bug or feature idea, it will suggest running /intake.
Use /memory-audit to check whether project memory artifacts still match
repository reality. This is a read-only, non-blocking command that produces an
advisory report at docs/engineering/memory-drift-report.md.
When to run:
/qa or /verify-work./release.How to interpret output:
The report contains a severity summary (high / medium / low) and a
findings table with concrete evidence for each inconsistency. High-severity
findings should be resolved before the next handoff or release. Medium and low
findings can be addressed during /refresh-context or the next sprint.
The report also includes a reference-only "Template drift" section. Template
drift remediation belongs to US-0017 — /memory-audit only flags it for
awareness.
Follow-up commands:
/refresh-context — update stale artifacts./sprint-plan — if new work is discovered./verify-work — if acceptance status needs re-validation./intake — if findings reveal a new story or bug.flowchart TD
Intake[/intake/] --> Discovery[/discovery/]
Discovery --> Research[/research/]
Research --> Architecture[/architecture/]
Architecture --> SprintPlan[/sprint-plan/]
SprintPlan --> PlanVerify[/plan-verify/]
PlanVerify --> Execute[/execute/]
Execute --> QA[/qa/]
QA -->|fixes needed| Execute
QA --> VerifyWork[/verify-work/]
VerifyWork --> Release[/release/]
Release --> Refresh[/refresh-context/]
Execute --> Pause[/pause/]
QA --> Pause
Release --> Pause
Pause --> Resume[/resume/]
Resume --> Execute
flowchart TD
Start[Idea] --> Intake2[/intake/]
Intake2 -->|DecisionGate| Decision{DecisionRequired}
Decision -->|ChooseOption| Discovery2[/discovery/]
Decision -->|ChooseOption| Research2[/research/]
Decision -->|ChooseOption| Architecture2[/architecture/]
Decision -->|ChooseOption| SprintPlan2[/sprint-plan/]
Decision -->|ChooseOption| PlanVerify2[/plan-verify/]
Decision -->|ChooseOption| Execute2[/execute/]
Decision -->|ChooseOption| QA2[/qa/]
Decision -->|ChooseOption| VerifyWork2[/verify-work/]
Decision -->|ChooseOption| Release2[/release/]
Decision -->|ChooseOption| Refresh2[/refresh-context/]
Decision -->|ChooseOption| Pause2[/pause/]
Discovery2 --> Research2
Research2 --> Architecture2
Architecture2 --> SprintPlan2
SprintPlan2 --> PlanVerify2
PlanVerify2 --> Execute2
Execute2 --> QA2
QA2 -->|fixes needed| Execute2
QA2 --> VerifyWork2
VerifyWork2 --> Release2
Release2 --> Refresh2
Execute2 --> Pause2
QA2 --> Pause2
Release2 --> Pause2
Pause2 --> Resume2[/resume/]
Resume2 --> Execute2
Execute2 --> HandoffDevQA[handoffs/dev_to_qa.md]
QA2 --> HandoffQAD[handoffs/qa_to_dev.md]
Intake2 --> HandoffPOTL[handoffs/po_to_tl.md]
SprintPlan2 --> HandoffTLDev[handoffs/tl_to_dev.md]
Configure in .cursor/scratchpad.md:
AUTO_FLOW_MODE=manual|auto_until_decision
manual: you trigger each phase/command yourself.auto_until_decision: /auto continues by spawning fresh phase subagents until a decision gate, blocker, or pause boundary.PHASE_MODE=interactive|auto
interactive: agent asks clarifying questions more often.auto: agent minimizes prompts and proceeds with best effort.PERMISSION_MODE=interactive|auto
interactive: ask before routine actions.auto: reduce routine permission prompts.RUN_TESTS_ON_EDIT=0|1
1: runs configured tests after meaningful edits.0: tests only when you explicitly run QA/test phases.LOOP_UNTIL_GREEN=0|1
1: keep iterating fix -> test until green (bounded).0: run one pass and report failures.AUTO_IMPLEMENTATION_LOOP=0|1
1: enables execute -> QA -> execute loop automatically with new Dev/QA subagent instances on each cycle.AUTO_LOOP_MAX_CYCLES=<n>
3-7, default 5).AUTO_PAUSE_REQUEST=0|1
1: request graceful stop at next safe boundary.AUTO_PAUSE_POLICY=after_task|after_phase
after_task: faster stop, more frequent boundaries.after_phase: cleaner checkpoints, fewer interruptions.Phase-triggered sync is policy-controlled and safe by default.
Scratchpad controls:
SYNC_POLICY_MODE=disabled|manual|by_phase|by_milestone|custom_phase_listSYNC_CUSTOM_PHASES=<comma-separated canonical phases>ALLOW_AUTO_PUSH=0|1AUTO_PUSH_BRANCH_ALLOWLIST=<comma-separated branches/patterns>Default-safe behavior:
manual with ALLOW_AUTO_PUSH=0 (no automatic push).disabled and manual add near-zero overhead and preserve manual workflows.Guarded auto-push conditions (all must pass):
ALLOW_AUTO_PUSH=1).TEST_COMMAND required; optional lint/typecheck only if configured).Deterministic reason codes include:
SYNC_DISABLED, MANUAL_MODE_NO_AUTO, PRE_QA_AUTOPUSH_FORBIDDEN,
BLOCKING_QA_FINDINGS, BRANCH_NOT_ALLOWLISTED, TEST_COMMAND_MISSING,
TEST_FAILED, TEST_TIMEOUT, OPTIONAL_CHECK_FAILED, SYNC_PUSHED.
MAGIC_CONTEXT_STRICT=0|1
1: enforces context refresh discipline after code edits.DONE=0|1
1: stop hook reminder loops when session is complete.MAGIC_BENCH_SESSION=<id>
AUTO_INSTALL_DEPS=0|1
1: agent may install dependencies/runtimes automatically.AUTO_RELEASE_NOTES=0|1
1: auto-generate handoffs/release_notes.md.REMOTE_EXECUTION=0|1
1: allow remote/docker execution if configured.REMOTE_CONFIG=.cursor/remote.json
.cursor/remote.json)Remote config is optional and mode-aware:
REMOTE_EXECUTION=0 (default): skip remote config checks entirely.REMOTE_EXECUTION=1: validate .cursor/remote.json first and fail fast on
missing/malformed/invalid or insecure config.Canonical contract (DEC-0016):
version (integer)defaultTarget (string)targets (array)id (string)type (docker|ssh|vm)enabled (boolean)host (string)port (integer 1..65535)workspaceRoot (string)auth.mode (none|env)auth.mode=env, use env-var references only (tokenEnv,
passwordEnv, privateKeyPathEnv, ...).Two safe target examples are shipped in:
.cursor/remote.json (active repo)template/.cursor/remote.json (template parity copy)The examples include:
local-docker: local network/docker-like endpoint.remote-vm-ssh: remote VM/SSH-like endpoint.No secrets policy:
remote.json.Fail-fast error format:
[REMOTE_CONFIG_ERROR] <path>: expected <rule>, got <actual>. Fix: <hint>.Troubleshooting quick guide:
.cursor/remote.json from the template copy, or set
REMOTE_EXECUTION=0.Team/local (recommended in .cursor/scratchpad.local.md):
TEAM_MODE=0|1TEAM_MEMBER=<your-id>ACTIVE_TASK_IDS=T-12,T-13Enable:
AUTO_FLOW_MODE=auto_until_decisionPHASE_MODE=autoPERMISSION_MODE=autoRUN_TESTS_ON_EDIT=1LOOP_UNTIL_GREEN=1AUTO_IMPLEMENTATION_LOOP=1AUTO_LOOP_MAX_CYCLES=5Then run /auto.
Graceful stop (for shutdown/end of day):
AUTO_PAUSE_REQUEST=1AUTO_PAUSE_POLICY)/pause artifacts are written/resume or /autoMax automation (high autonomy):
AUTO_FLOW_MODE=auto_until_decisionPHASE_MODE=autoPERMISSION_MODE=autoRUN_TESTS_ON_EDIT=1LOOP_UNTIL_GREEN=1AUTO_IMPLEMENTATION_LOOP=1AUTO_LOOP_MAX_CYCLES=5AUTO_INSTALL_DEPS=1 (optional, if you trust auto installs)AUTO_PAUSE_POLICY=after_phaseSafer automation (recommended for most teams):
PERMISSION_MODE=interactiveAUTO_INSTALL_DEPS=0AUTO_PAUSE_POLICY=after_taskits-magic provides a complete quality chain that catches issues at three levels. Each layer catches problems the previous layer missed:
┌─────────────────────────────────────────────────────────────────┐
│ Layer 1: Cursor AI loop (in-editor) OFF by default │
│ AUTO_IMPLEMENTATION_LOOP + LOOP_UNTIL_GREEN │
│ execute → QA → fix → execute (bounded by AUTO_LOOP_MAX_CYCLES)│
└──────────────────────────┬──────────────────────────────────────┘
│ code ready to push
┌──────────────────────────▼──────────────────────────────────────┐
│ Layer 2: validate-and-push (local pre-push) MANUAL (run it)│
│ scripts/validate-and-push.sh / .ps1 │
│ test → format → lint-fix → test → commit + push │
└──────────────────────────┬──────────────────────────────────────┘
│ pushed to GitHub
┌──────────────────────────▼──────────────────────────────────────┐
│ Layer 3: CI auto-fix (GitHub Actions) OFF by default │
│ .github/workflows/ci.yml │
│ test/lint → auto-fix → commit → re-run (up to 3 retries) │
└─────────────────────────────────────────────────────────────────┘
| Layer | Default | Enable |
|---|---|---|
| 1 - Cursor AI loop | off | Set AUTO_IMPLEMENTATION_LOOP=1 + LOOP_UNTIL_GREEN=1 in scratchpad |
| 2 - validate-and-push | manual | Run scripts/validate-and-push.sh or .ps1 before pushing |
| 3 - CI auto-fix | off | Set CI_AUTO_FIX: true in docs/engineering/runbook.md |
CI itself (tests, lint, typecheck) always runs on push/PR. Only the auto-fix
retry loop is gated behind CI_AUTO_FIX. When disabled, CI still reports
failures -- it just won't try to fix and commit automatically.
All commands are read from docs/engineering/runbook.md. Fill in your
project-specific commands once and every layer uses them:
TEST_COMMAND: npm test
LINT_COMMAND: npx eslint .
LINT_FIX_COMMAND: npx eslint --fix .
FORMAT_COMMAND: npx prettier --write .
CI_AUTO_FIX: true
Enabled via scratchpad flags (see Automation modes).
The AI runs execute → QA → fix cycles inside Cursor until tests pass or
the safety cap (AUTO_LOOP_MAX_CYCLES) is reached.
Run before pushing to catch anything the AI loop missed. Merged scratchpad (see
docs/engineering/runbook.md, Executable validate-and-push wiring (DEC-0058)) gates
git push: default SYNC_POLICY_MODE=manual and ALLOW_AUTO_PUSH=0 exit early
with a reason code (no push). Opt-in push requires an eligible mode, ALLOW_AUTO_PUSH=1,
a non-empty branch allowlist match, passing runbook checks, and bounded QA rules.
# Bash (Linux / macOS; bash required for this script)
bash scripts/validate-and-push.sh
# PowerShell (Windows)
powershell scripts/validate-and-push.ps1
powershell scripts/validate-and-push.ps1 -MaxAttempts 3
powershell scripts/validate-and-push.ps1 -DryRun
The script:
python scripts/sync_push_gates.py (Python 3 on PATH)FORMAT_COMMAND and LINT_FIX_COMMAND to auto-fix what it canLINT_COMMAND, optional TYPECHECK_COMMAND, and TEST_COMMAND to verify (with TEST_TIMEOUT_SECONDS when timeout/gtimeout is available on Unix)Use -NoCommit (PowerShell), --dry-run first arg (Bash), or false as third arg (Bash) to skip push.
Policy-only interpretation of scratchpad sync flags is deprecated for these scripts; see decisions/DEC-0058.md (policy semantics remain DEC-0018 / US-0038).
Disabled by default. Set CI_AUTO_FIX: true in docs/engineering/runbook.md
to enable. When enabled and CI fails after a push, the auto-fix job kicks in:
push / PR ──> checks ──> PASS ──> done
│
FAIL
│
auto-fix job
│
run LINT_FIX_COMMAND
run FORMAT_COMMAND
│
changes found?
╱ ╲
yes no
│ │
commit + push report failure
│ (manual fix needed)
CI re-runs
(up to 3x)
Auto-fix commits appear as ci: auto-fix attempt N/3. After 3 retries the
workflow stops and points you to scripts/validate-and-push for local fixing.
/intake/research/architecture/sprint-plan/plan-verify/execute/qa/verify-work/release/refresh-contextAUTO_PAUSE_REQUEST=1/intake to update story/acceptance/sprint-plan + /plan-verify/auto/pause/resume next session/auto continuationWhen resuming mid-process, /auto resolves start phase deterministically:
/auto start-from=<phase>handoffs/resume_brief.mddocs/engineering/state.md fallbackCanonical phases:
intake, discovery, research, architecture, sprint-plan,
plan-verify, execute, qa, verify-work, release, refresh-context.
Fail-fast message format:
[AUTO_RESUME_ERROR] <code>: <summary>. Source=<source>. Fix: <action>.
Compatibility and safety:
/auto continuation is used./auto backlog-drain mode (US-0044)If you want /auto to continue across multiple planned stories in one run,
enable backlog-drain switches in .cursor/scratchpad.md:
AUTO_BACKLOG_DRAIN=1AUTO_BACKLOG_MAX_STORIES=<n>AUTO_BACKLOG_ON_BLOCK=stop|skipAUTO_STORY_SELECTION=priority_then_backlog_orderDefault-safe behavior remains unchanged with AUTO_BACKLOG_DRAIN=0.
/sprint-plan --bulk mode (US-0046)By default, /sprint-plan plans one scope at a time. For multi-story planning,
run explicit bulk mode:
/sprint-plan --bulkBulk planning remains bounded and deterministic via .cursor/scratchpad.md:
SPRINT_BULK_MAX_STORIES=<n>SPRINT_BULK_MAX_SPRINTS=<n>SPRINT_BULK_SELECTION=priority_then_backlog_orderBounded stop reason codes:
SPRINT_BULK_MAX_STORIES_REACHED, SPRINT_BULK_MAX_SPRINTS_REACHED,
SPRINT_BULK_NO_ELIGIBLE_STORIES, SPRINT_BULK_MISSING_ACCEPTANCE.
/auto --execute-bulk mode (US-0047)Bulk execution is explicit-mode only. Default /auto behavior remains unchanged.
Enable either way:
/auto --execute-bulkAUTO_EXECUTE_BULK=1Deterministic controls in .cursor/scratchpad.md:
AUTO_EXECUTE_MAX_ITEMS=<n>AUTO_EXECUTE_ON_BLOCK=stop|skipAUTO_EXECUTE_SELECTION=planned_then_priorityAUTO_TEAM_SCOPE_ENFORCE=0|1Deterministic reason codes:
EXEC_BULK_MAX_ITEMS_REACHED, EXEC_BULK_NO_ELIGIBLE_ITEMS,
EXEC_BULK_ITEM_BLOCKED_STOP, EXEC_BULK_ITEM_BLOCKED_SKIPPED,
EXEC_TEAM_SCOPE_BLOCKED, EXEC_TEAM_SCOPE_SKIPPED.
Team-mode safety:
TEAM_MODE=1, bulk execute records TEAM_MODE, TEAM_MEMBER,
ACTIVE_TASK_IDS in state breadcrumbs.AUTO_TEAM_SCOPE_ENFORCE=1, out-of-scope tasks are blocked/skipped
deterministically and never mutated./map-codebase/intake or /architectureVoice is an input layer only; it feeds normal slash commands.
Reliable pattern:
/intake insertion shortcut.cursor/: commands, rules, agents, hooks, skills, scratchpad.docs/: product + engineering docs.sprints/: sprint planning/tracking.handoffs/: role-to-role transfers.decisions/: decision records..github/workflows/: CI/CD templates.Workflows read keys from docs/engineering/runbook.md:
TEST_COMMANDLINT_COMMANDTYPECHECK_COMMANDDEPLOY_STAGING_COMMANDDEPLOY_PROD_COMMANDUnset keys are skipped. The template ships with empty values for LINT_COMMAND,
FORMAT_COMMAND, and TYPECHECK_COMMAND -- this is intentional. its-magic is a
template/installer project; fill in your project-specific commands after setup.
US-0015 intent contract:
installer.ps1 (Windows)installer.sh (macOS/Linux)installer.py (fallback)Modes: missing, overwrite, interactive, upgrade (+ optional backup).
Unified release scripts:
scripts/release-all.ps1scripts/release-all.shNPM helpers:
npm run release:allnpm run release:all:patch|minor|major|beta|drynpm run release:npm-only|choco-only|brew-onlyRelease script flow:
package.json versionflowchart LR
ReleaseAll[scripts/release-all.*] --> VerCheck{version has -?}
VerCheck -->|stable| NPM["npm publish --tag latest"]
VerCheck -->|prerelease| NPMBeta["npm publish --tag beta"]
ReleaseAll --> GH["gh release create"]
VerCheck -->|prerelease| GHPre["--prerelease flag"]
GH --> Choco[choco pack + push]
GH --> BrewCheck{prerelease?}
BrewCheck -->|no| BrewStable[its-magic.rb]
BrewCheck -->|yes| BrewBeta[its-magic-beta.rb]
NPM --> U1["npx its-magic"]
NPMBeta --> U1b["npx its-magic@beta"]
Choco --> U2["choco install its-magic"]
Choco --> U2b["choco install its-magic --pre"]
BrewStable --> U3["brew install its-magic"]
BrewBeta --> U3b["brew install its-magic-beta"]
Prereqs:
npm logingh auth login| Manager | Stable | Beta / Pre-release |
|---|---|---|
| npm/npx | npx its-magic --target . --mode missing | npx its-magic@beta --target . --mode missing |
| Chocolatey | choco install its-magic | choco install its-magic --pre |
| Homebrew | brew install USER/tap/its-magic | brew install USER/tap/its-magic-beta |
Published npm package includes runtime content only (commands/rules/agents/docs/installers).
Excluded from npm package:
benchmarks/tests/packaging/Plan.mdbenchmarks/run-bench.ps1 or benchmarks/run-bench.shbenchmarks/live/run-live-bench.*benchmarks/prompts/run-prompts.*benchmarks/headless/run-headless.*Reports:
benchmarks/bench-report.mdbenchmarks/live/live-bench-report.mdbenchmarks/headless/headless-report.mdbenchmarks/headless/protocol.mdflowchart TD
StartBench[Start benchmark] --> SelectScenario[Load scenarios]
SelectScenario --> InstallKit[Install its-magic into temp workspace]
InstallKit --> RunChecks[Validate required files/sections]
RunChecks --> BenchReport[Write benchmarks/bench-report.md]
flowchart TD
StartLive[Start live benchmark] --> SetSession[Set MAGIC_BENCH_SESSION]
SetSession --> RunCommands[Run /* commands in Cursor]
RunCommands --> LogHooks[Hook telemetry to bench-log.jsonl]
LogHooks --> LiveReport[Write live-bench-report.md]
flowchart TD
StartHeadless[Start headless run] --> LoadPrompt[Load prompt blocks]
LoadPrompt --> TempWorkspace[Create temp workspace]
TempWorkspace --> InstallHeadless[Install its-magic]
InstallHeadless --> RunAgent[agent -p --force for each step]
RunAgent --> ValidateOutputs[Validate files/sections/smoke checks]
ValidateOutputs --> WriteProtocol[Write protocol.md]
WriteProtocol --> WriteHeadlessReport[Write headless-report.md]
core.mdc: phase flow, context pack, pause/resume, remote usage.quality.mdc: small steps, tests/quality, optional auto-install.coding-standards.mdc: strict language best practices and code quality rules.handoffs.mdc: handoffs + state updates required.escalation.mdc: decision gate and stop conditions.beforeShellExecution: blocks dangerous commands.beforeReadFile: warns on secret-like files.afterFileEdit: tracks code edits vs context refresh.stop: reminds context refresh when needed.docs/product/*: vision, backlog, acceptance.docs/engineering/*: architecture, decisions, state, runbook.sprints/Sxxxx/*: sprint scope, tasks, progress, QA findings, summary.decisions/*: decision records.handoffs/*: role-to-role transfer notes.This repository publishes the its-magic workflow kit: commands, rules, skills, and documentation templates that teams install into their own repositories. The goal is a repeatable, file-backed lifecycle from intake through release.
Use Setup for install commands. First-time install:
npx its-magic --target . --mode missing --create
its-magic --target . --mode upgradeTEST_COMMAND from docs/engineering/runbook.md (often sh tests/run-tests.sh).docs/engineering/runbook.mddocs/engineering/architecture.mddocs/product/backlog.md, docs/product/acceptance.mdSPEC_PACK_MODE=1): engineering design artifacts under docs/engineering/ when your team enables itUSER_GUIDE_MODE=1): docs/user-guides/ when enabledREADME.md are preserved on upgrade; review notices may appear when
the template adds new sections.scripts/validate_doc_profile.py) enforces audience and
depth choices from the merged scratchpad (DOC_AUDIENCE_PROFILE, DOC_DETAIL_LEVEL).Contributor-focused workflow and guardrails live in
docs/developer/README.md.
FAQs
its-magic - AI dev team workflow for Cursor.
We found that its-magic demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.