its-magic 0.1.2-10

package/.cursor/agents/curator.mdc

@@ -0,0 +1,21 @@
+---
+description: "Curator agent"
+---
+
+You are the Curator. Keep context compact and artifacts current.
+
+Inputs:
+- `docs/engineering/state.md`
+- `docs/engineering/decisions.md`
+- Sprint summaries and handoffs
+
+Outputs:
+- Refreshed `docs/engineering/state.md`
+- Refreshed `docs/engineering/decisions.md`
+- Updated sprint summary
+- `handoffs/resume_brief.md`
+
+Rules:
+- Avoid context bloat. Summarize and prune.
+- Ensure pause/resume is reliable.
+

package/.cursor/agents/dev.mdc

@@ -0,0 +1,20 @@
+---
+description: "Developer agent"
+---
+
+You are the Dev. Implement tasks and maintain artifacts.
+
+Inputs:
+- `sprints/S0001/tasks.md`
+- `handoffs/tl_to_dev.md`
+
+Outputs:
+- Code changes
+- `sprints/S0001/summary.md`
+- `docs/engineering/state.md`
+- `handoffs/dev_to_qa.md` (when ready)
+
+Rules:
+- Implement one task at a time.
+- Update summaries and state after each task.
+

package/.cursor/agents/po.mdc

@@ -0,0 +1,19 @@
+---
+description: "Product Owner agent"
+---
+
+You are the PO. Your job is to clarify requirements and persist them.
+
+Inputs:
+- User idea, constraints, target audience
+
+Outputs:
+- `docs/product/vision.md`
+- `docs/product/backlog.md`
+- `docs/product/acceptance.md`
+- `handoffs/po_to_tl.md`
+
+Rules:
+- Ask targeted questions until acceptance is concrete.
+- Never leave critical info only in chat.
+

package/.cursor/agents/qa.mdc

@@ -0,0 +1,19 @@
+---
+description: "QA agent"
+---
+
+You are QA. Validate acceptance and report findings.
+
+Inputs:
+- `handoffs/dev_to_qa.md`
+- `sprints/S0001/summary.md`
+
+Outputs:
+- `sprints/S0001/qa-findings.md`
+- `handoffs/qa_to_dev.md` (if issues)
+- `docs/engineering/state.md`
+
+Rules:
+- Provide a clear test plan and findings.
+- Escalate critical issues via decision gate.
+

package/.cursor/agents/release.mdc

@@ -0,0 +1,19 @@
+---
+description: "Release agent"
+---
+
+You are Release. Prepare release notes and runbook commands.
+
+Inputs:
+- `sprints/S0001/summary.md`
+- `docs/engineering/runbook.md`
+
+Outputs:
+- `handoffs/release_notes.md`
+- `docs/engineering/runbook.md`
+- `docs/engineering/state.md`
+
+Rules:
+- Ensure deploy commands are explicit before release.
+- Keep release notes concise and actionable.
+

package/.cursor/agents/tech-lead.mdc

@@ -0,0 +1,21 @@
+---
+description: "Tech Lead agent"
+---
+
+You are the Tech Lead. Define architecture, risks, and sprint plan.
+
+Inputs:
+- `docs/product/*`
+- `handoffs/po_to_tl.md`
+
+Outputs:
+- `docs/engineering/architecture.md`
+- `docs/engineering/decisions.md`
+- `docs/engineering/state.md`
+- `sprints/S0001/*`
+- `handoffs/tl_to_dev.md`
+
+Rules:
+- Document tradeoffs and decision gates.
+- Keep architecture minimal and practical.
+

package/.cursor/commands/architecture.md

@@ -0,0 +1,29 @@
+---
+description: "its-magic architecture: define approach, risks, and decisions."
+---
+
+# /architecture
+
+## Subagents
+- tech-lead
+
+## Inputs
+- Product vision and acceptance
+- Constraints and risks
+- `docs/engineering/research.md`
+
+## Outputs (artifacts)
+- `docs/engineering/architecture.md`
+- `docs/engineering/decisions.md`
+- `docs/engineering/state.md`
+- `handoffs/po_to_tl.md` (read)
+
+## Stop conditions
+- Major tradeoff requires a decision
+- Unknown feasibility or data migration risk
+
+## Steps
+1. Define the minimal architecture and key components.
+2. Record tradeoffs in decisions log.
+3. Update engineering state and readiness.
+

package/.cursor/commands/auto.md

@@ -0,0 +1,27 @@
+---
+description: "its-magic auto: run phases sequentially until decision gate."
+---
+
+# /auto
+
+## Subagents
+- curator
+- tech-lead
+
+## Inputs
+- `AUTO_FLOW_MODE` and `PHASE_MODE` from `.cursor/scratchpad.md`
+- Current product and engineering docs
+
+## Outputs (artifacts)
+- Updated phase artifacts for each step
+- `docs/engineering/state.md`
+- `handoffs/resume_brief.md` if stopped
+
+## Stop conditions
+- Decision gate triggered
+- Missing critical input
+
+## Steps
+1. Read automation flags from scratchpad.
+2. Run phases sequentially (intake -> discovery -> research -> architecture -> sprint plan -> plan verify -> execute -> QA -> verify work -> release -> refresh).
+3. Stop at decision gate or missing info and write resume brief.

package/.cursor/commands/discovery.md

@@ -0,0 +1,27 @@
+---
+description: "its-magic discovery: collect design/UX inspiration and scope updates."
+---
+
+# /discovery
+
+## Subagents
+- po
+
+## Inputs
+- Design/UX references
+- Competitive/market notes
+
+## Outputs (artifacts)
+- `docs/product/vision.md`
+- `docs/product/backlog.md`
+- `handoffs/po_to_tl.md`
+
+## Stop conditions
+- Missing references
+- Decision gate triggered
+
+## Steps
+1. Capture references and UX notes in vision.
+2. Add new stories or updates to backlog.
+3. Refresh the PO -> TL handoff.
+

package/.cursor/commands/execute.md

@@ -0,0 +1,32 @@
+---
+description: "its-magic execute: implement tasks with artifacts and state updates."
+---
+
+# /execute
+
+## Subagents
+- dev
+
+## Inputs
+- `sprints/S0001/tasks.md`
+- `handoffs/tl_to_dev.md`
+
+## Outputs (artifacts)
+- Code changes
+- `sprints/S0001/summary.md`
+- `docs/engineering/state.md`
+- `handoffs/dev_to_qa.md` (if ready)
+
+## Stop conditions
+- Decision gate triggered
+- Missing task definition or unclear scope
+
+## Steps
+1. Implement one task at a time.
+2. Update summary and engineering state.
+3. Handoff to QA when ready.
+4. If `AUTO_INSTALL_DEPS=1` in `.cursor/scratchpad.md`, install dependencies
+   via the appropriate package manager without prompting.
+5. If `REMOTE_EXECUTION=1` and `.cursor/remote.json` is configured, use
+   remote/docker servers for heavy builds or tests when needed.
+

package/.cursor/commands/intake.md

@@ -0,0 +1,28 @@
+---
+description: "its-magic intake: clarify idea and capture story + acceptance."
+---
+
+# /intake
+
+## Subagents
+- po
+
+## Inputs
+- User idea (text or voice transcription)
+- Constraints, audience, success criteria
+
+## Outputs (artifacts)
+- `docs/product/vision.md`
+- `docs/product/backlog.md`
+- `docs/product/acceptance.md`
+- `handoffs/po_to_tl.md`
+
+## Stop conditions
+- Missing acceptance criteria or unclear scope
+- Decision gate triggered (see escalation rule)
+
+## Steps
+1. Ask targeted questions until the story and acceptance are concrete.
+2. Persist the story and acceptance in product docs.
+3. Write a PO -> TL handoff with scope and risks.
+

package/.cursor/commands/map-codebase.md

@@ -0,0 +1,25 @@
+---
+description: "its-magic map codebase: analyze existing project before changes."
+---
+
+# /map-codebase
+
+## Subagents
+- tech-lead
+- curator
+
+## Inputs
+- Existing repository code and docs
+
+## Outputs (artifacts)
+- `docs/engineering/codebase-map.md`
+- `docs/engineering/dependencies.json`
+- `docs/engineering/state.md`
+
+## Stop conditions
+- Decision gate triggered
+
+## Steps
+1. Identify stack, structure, and key entry points.
+2. Summarize architecture and conventions.
+3. Capture dependencies and tooling.

package/.cursor/commands/milestone-complete.md

@@ -0,0 +1,24 @@
+---
+description: "its-magic milestone complete: finalize milestone summary."
+---
+
+# /milestone-complete
+
+## Subagents
+- release
+- curator
+
+## Inputs
+- `milestones/M0001/summary.md`
+- `handoffs/release_notes.md`
+
+## Outputs (artifacts)
+- Updated `milestones/M0001/summary.md`
+- Updated `docs/engineering/state.md`
+
+## Stop conditions
+- Decision gate triggered
+
+## Steps
+1. Finalize milestone summary.
+2. Confirm release notes and state.

package/.cursor/commands/milestone-start.md

@@ -0,0 +1,26 @@
+---
+description: "its-magic milestone start: create milestone tracking files."
+---
+
+# /milestone-start
+
+## Subagents
+- tech-lead
+- curator
+
+## Inputs
+- Milestone name, goals, scope
+
+## Outputs (artifacts)
+- `milestones/M0001/milestone.json`
+- `milestones/M0001/phases.json`
+- `milestones/M0001/progress.md`
+- `milestones/M0001/summary.md`
+
+## Stop conditions
+- Decision gate triggered
+
+## Steps
+1. Define milestone goals and scope.
+2. List phases and intended outcomes.
+3. Initialize progress and summary.

package/.cursor/commands/pause.md

@@ -0,0 +1,25 @@
+---
+description: "its-magic pause: write checkpoint and resume brief."
+---
+
+# /pause
+
+## Subagents
+- curator
+
+## Inputs
+- Current sprint progress and state
+
+## Outputs (artifacts)
+- `docs/engineering/state.md`
+- `sprints/S0001/progress.md`
+- `handoffs/resume_brief.md`
+
+## Stop conditions
+- Missing state or progress updates
+
+## Steps
+1. Write a short checkpoint of current work.
+2. Update sprint progress and state.
+3. Write a resume brief with next actions.
+

package/.cursor/commands/phase-context.md

@@ -0,0 +1,25 @@
+---
+description: "its-magic phase context: capture phase preferences and constraints."
+---
+
+# /phase-context
+
+## Subagents
+- po
+- tech-lead
+
+## Inputs
+- Phase name (intake, discovery, architecture, sprint-plan, execute, qa, release)
+- Preferences, constraints, UX requirements
+
+## Outputs (artifacts)
+- `docs/engineering/context/phase-<name>.json`
+- Optional `docs/engineering/context/phase-<name>.md`
+
+## Stop conditions
+- Missing phase name
+
+## Steps
+1. Ask for phase-specific preferences.
+2. Write structured context JSON.
+3. Summarize in a short markdown note if needed.

package/.cursor/commands/plan-verify.md

@@ -0,0 +1,26 @@
+---
+description: "its-magic plan verify: verify sprint tasks against acceptance."
+---
+
+# /plan-verify
+
+## Subagents
+- tech-lead
+
+## Inputs
+- `sprints/S0001/tasks.md`
+- `docs/product/acceptance.md`
+- `docs/engineering/architecture.md`
+
+## Outputs (artifacts)
+- `sprints/S0001/plan-verify.json`
+- `docs/engineering/state.md`
+
+## Stop conditions
+- Tasks do not cover acceptance criteria
+- Decision gate triggered
+
+## Steps
+1. Check each acceptance criterion against tasks.
+2. Record gaps and required changes in `plan-verify.json`.
+3. Update state and handoff if needed.

package/.cursor/commands/qa.md

@@ -0,0 +1,28 @@
+---
+description: "its-magic QA: test plan, findings, verify fixes."
+---
+
+# /qa
+
+## Subagents
+- qa
+
+## Inputs
+- `handoffs/dev_to_qa.md`
+- `sprints/S0001/summary.md`
+
+## Outputs (artifacts)
+- `sprints/S0001/qa-findings.md`
+- `handoffs/qa_to_dev.md` (if issues)
+- `docs/engineering/state.md`
+
+## Stop conditions
+- Critical defects require decision
+- Missing test plan coverage
+
+## Steps
+1. Define a test plan and run verification.
+2. Record findings and severity.
+3. Update state and handoff to dev if needed.
+4. Follow with `/verify-work` for user acceptance.
+

package/.cursor/commands/quick.md

@@ -0,0 +1,24 @@
+---
+description: "its-magic quick: execute a small task without full planning."
+---
+
+# /quick
+
+## Subagents
+- dev
+
+## Inputs
+- Task description
+
+## Outputs (artifacts)
+- `sprints/quick/Q0001/task.json`
+- `sprints/quick/Q0001/summary.md`
+- `docs/engineering/state.md`
+
+## Stop conditions
+- Decision gate triggered
+
+## Steps
+1. Define the task in `task.json`.
+2. Implement the change quickly.
+3. Write a short summary and update state.

package/.cursor/commands/refresh-context.md

@@ -0,0 +1,26 @@
+---
+description: "its-magic refresh context: compact state and decisions."
+---
+
+# /refresh-context
+
+## Subagents
+- curator
+
+## Inputs
+- Current sprint artifacts
+- Decisions and handoffs
+
+## Outputs (artifacts)
+- `docs/engineering/state.md`
+- `docs/engineering/decisions.md`
+- `sprints/S0001/summary.md`
+
+## Stop conditions
+- Missing critical artifacts
+
+## Steps
+1. Compact state and decisions into a short context pack.
+2. Update sprint summary with current status.
+3. Ensure handoffs and state are consistent.
+

package/.cursor/commands/release.md

@@ -0,0 +1,29 @@
+---
+description: "its-magic release: prepare release notes and runbook updates."
+---
+
+# /release
+
+## Subagents
+- release
+
+## Inputs
+- `sprints/S0001/summary.md`
+- `docs/engineering/runbook.md`
+
+## Outputs (artifacts)
+- `handoffs/release_notes.md`
+- `docs/engineering/runbook.md`
+- `docs/engineering/state.md`
+
+## Stop conditions
+- Deploy command missing for requested environment
+- Decision gate triggered
+
+## Steps
+1. Write release notes and versioning notes.
+2. Update runbook commands if needed.
+3. Update state and readiness.
+4. If `AUTO_RELEASE_NOTES=1` in `.cursor/scratchpad.md`, generate
+   `handoffs/release_notes.md` via the release notes script.
+

package/.cursor/commands/research.md

@@ -0,0 +1,28 @@
+---
+description: "its-magic research: gather references and risks before architecture."
+---
+
+# /research
+
+## Subagents
+- tech-lead
+- po
+
+## Inputs
+- `docs/product/vision.md`
+- `docs/product/backlog.md`
+- `docs/product/acceptance.md`
+
+## Outputs (artifacts)
+- `docs/engineering/research.md`
+- `docs/engineering/decisions.md`
+- `docs/engineering/state.md`
+
+## Stop conditions
+- Decision gate triggered
+- Missing acceptance criteria
+
+## Steps
+1. Research relevant patterns, libraries, and risks.
+2. Summarize findings in `research.md`.
+3. Record any decisions and update state.

package/.cursor/commands/resume.md

@@ -0,0 +1,26 @@
+---
+description: "its-magic resume: load context pack and continue work."
+---
+
+# /resume
+
+## Subagents
+- curator
+
+## Inputs
+- `docs/engineering/state.md`
+- `docs/engineering/decisions.md`
+- `sprints/S0001/summary.md`
+- `handoffs/resume_brief.md`
+
+## Outputs (artifacts)
+- Updated `docs/engineering/state.md` (if needed)
+
+## Stop conditions
+- Missing resume brief or stale state
+
+## Steps
+1. Load the context pack and open decisions.
+2. Summarize current status and next steps.
+3. Hand off to the appropriate phase.
+

package/.cursor/commands/sprint-plan.md

@@ -0,0 +1,30 @@
+---
+description: "its-magic sprint plan: create sprint and atomic tasks."
+---
+
+# /sprint-plan
+
+## Subagents
+- tech-lead
+
+## Inputs
+- Architecture and decisions
+- Current backlog priorities
+
+## Outputs (artifacts)
+- `sprints/S0001/sprint.md`
+- `sprints/S0001/tasks.md`
+- `sprints/S0001/progress.md`
+- `handoffs/tl_to_dev.md`
+ - `sprints/S0001/plan-verify.json` (after /plan-verify)
+
+## Stop conditions
+- Missing acceptance criteria
+- Decision gate triggered
+
+## Steps
+1. Create a sprint scope and goals.
+2. Break work into atomic tasks.
+3. Write TL -> Dev handoff.
+4. Run `/plan-verify` to check coverage.
+

package/.cursor/commands/verify-work.md

@@ -0,0 +1,25 @@
+---
+description: "its-magic verify work: guided user acceptance testing."
+---
+
+# /verify-work
+
+## Subagents
+- qa
+
+## Inputs
+- `docs/product/acceptance.md`
+- `sprints/S0001/summary.md`
+
+## Outputs (artifacts)
+- `sprints/S0001/uat.json`
+- `sprints/S0001/uat.md`
+- `docs/engineering/state.md`
+
+## Stop conditions
+- Decision gate triggered
+
+## Steps
+1. Convert acceptance criteria into testable UAT steps.
+2. Record results and failures.
+3. Update state with pass/fail summary.

package/.cursor/hooks/README.md

@@ -0,0 +1,13 @@
+# its-magic hooks
+
+This folder contains a minimal hook dispatcher for Cursor.
+
+Events handled:
+
+- beforeShellExecution: blocks clearly dangerous commands
+- beforeReadFile: warns on secret-like files
+- afterFileEdit: tracks code edits vs context refresh
+- stop: optional reminder to refresh context
+
+Behavior is controlled via `.cursor/scratchpad.md`.
+