its-magic 0.1.2-9

package/.cursor/hooks/gsd-hook.py

@@ -0,0 +1,197 @@
+import json
+import os
+import re
+import sys
+from datetime import datetime
+
+ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
+SCRATCHPAD = os.path.join(ROOT, ".cursor", "scratchpad.md")
+STATE_FILE = os.path.join(ROOT, ".cursor", "hooks", "gsd-hook-state.json")
+BENCH_LOG = os.path.join(ROOT, ".cursor", "hooks", "gsd-bench-log.jsonl")
+
+
+def read_scratchpad():
+    flags = {}
+    try:
+        with open(SCRATCHPAD, "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line or line.startswith("#"):
+                    continue
+                if "=" in line:
+                    key, val = line.split("=", 1)
+                    flags[key.strip()] = val.strip()
+    except OSError:
+        pass
+    return flags
+
+
+def load_state():
+    try:
+        with open(STATE_FILE, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except Exception:
+        return {
+            "code_changed": False,
+            "context_refreshed": False,
+            "last_edit": None,
+        }
+
+
+def save_state(state):
+    try:
+        with open(STATE_FILE, "w", encoding="utf-8") as f:
+            json.dump(state, f, indent=2)
+    except OSError:
+        pass
+
+
+def bench_session(flags):
+    session = flags.get("GSD_BENCH_SESSION", "").strip()
+    return session if session else None
+
+
+def log_bench_event(session, event, payload):
+    if not session:
+        return
+    try:
+        entry = {
+            "ts": datetime.utcnow().isoformat() + "Z",
+            "session": session,
+            "event": event,
+        }
+        if event == "beforeShellExecution":
+            cmd = payload.get("command", "")
+            entry["command"] = cmd[:200]
+        elif event == "beforeReadFile":
+            entry["path"] = payload.get("path", "")
+        elif event == "afterFileEdit":
+            entry["path"] = payload.get("path", "")
+        elif event == "stop":
+            entry["state"] = payload.get("state", "")
+        with open(BENCH_LOG, "a", encoding="utf-8") as f:
+            f.write(json.dumps(entry) + "\n")
+    except OSError:
+        pass
+
+
+def read_event_payload():
+    try:
+        data = sys.stdin.read()
+        if not data.strip():
+            return {}
+        return json.loads(data)
+    except Exception:
+        return {}
+
+
+def is_dangerous_command(cmd):
+    patterns = [
+        r"\brm\s+-rf\s+/",
+        r"\bdel\s+/f\s+/s\b",
+        r"\bformat\b",
+        r"\bmkfs\b",
+        r"\bdiskpart\b",
+        r"\bshutdown\b",
+        r"\breboot\b",
+        r"\bcurl\b.+\|\s*(sh|bash|pwsh|powershell)",
+    ]
+    return any(re.search(p, cmd, re.IGNORECASE) for p in patterns)
+
+
+def is_secret_like(path):
+    secrets = [
+        ".env",
+        "id_rsa",
+        "id_dsa",
+        ".pem",
+        ".key",
+        ".p12",
+        "credentials.json",
+    ]
+    lower = path.lower()
+    return any(s in lower for s in secrets)
+
+
+def is_code_path(path):
+    normalized = path.replace("\\", "/").lower()
+    if "/docs/" in normalized:
+        return False
+    if "/handoffs/" in normalized:
+        return False
+    if "/decisions/" in normalized:
+        return False
+    if "/sprints/" in normalized:
+        return False
+    if "/.cursor/" in normalized:
+        return False
+    if "/.github/" in normalized:
+        return False
+    if normalized.endswith("readme.md"):
+        return False
+    return True
+
+
+def is_context_refresh(path):
+    normalized = path.replace("\\", "/").lower()
+    return normalized.endswith("/docs/engineering/state.md") or normalized.endswith(
+        "/sprints/s0001/summary.md"
+    )
+
+
+def main():
+    if len(sys.argv) < 2:
+        sys.exit(0)
+
+    event = sys.argv[1]
+    flags = read_scratchpad()
+    payload = read_event_payload()
+    state = load_state()
+    session = bench_session(flags)
+
+    if event == "beforeShellExecution":
+        log_bench_event(session, event, payload)
+        cmd = payload.get("command", "")
+        if cmd and is_dangerous_command(cmd):
+            print("Blocked: dangerous command pattern detected.")
+            sys.exit(1)
+        sys.exit(0)
+
+    if event == "beforeReadFile":
+        log_bench_event(session, event, payload)
+        path = payload.get("path", "")
+        if path and is_secret_like(path):
+            print("Blocked: secret-like file detected. Confirm before reading.")
+            sys.exit(1)
+        sys.exit(0)
+
+    if event == "afterFileEdit":
+        log_bench_event(session, event, payload)
+        path = payload.get("path", "")
+        if path:
+            if is_code_path(path):
+                state["code_changed"] = True
+            if is_context_refresh(path):
+                state["context_refreshed"] = True
+            state["last_edit"] = datetime.utcnow().isoformat() + "Z"
+            save_state(state)
+        sys.exit(0)
+
+    if event == "stop":
+        log_bench_event(session, event, payload)
+        strict = flags.get("GSD_CONTEXT_STRICT", "0") == "1"
+        done = flags.get("DONE", "0") == "1"
+        if strict and state.get("code_changed") and not state.get("context_refreshed"):
+            if not done:
+                print(
+                    "Context refresh recommended: update state or summary after code edits."
+                )
+                sys.exit(1)
+        sys.exit(0)
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()
+

package/.cursor/hooks.json

@@ -0,0 +1,26 @@
+{
+  "version": 1,
+  "hooks": {
+    "beforeShellExecution": [
+      {
+        "command": "python .cursor/hooks/gsd-hook.py beforeShellExecution"
+      }
+    ],
+    "beforeReadFile": [
+      {
+        "command": "python .cursor/hooks/gsd-hook.py beforeReadFile"
+      }
+    ],
+    "afterFileEdit": [
+      {
+        "command": "python .cursor/hooks/gsd-hook.py afterFileEdit"
+      }
+    ],
+    "stop": [
+      {
+        "command": "python .cursor/hooks/gsd-hook.py stop"
+      }
+    ]
+  }
+}
+

package/.cursor/plans/cursor-gsd-team-kit_8cfee9b8.plan.md

@@ -0,0 +1,57 @@
+---
+name: cursor-gsd-team-kit
+overview: Plan the build of the Cursor-native “GSD Team Kit” template repo described in `Plan.md`, covering commands, rules, skills, agents, hooks, docs, and CI/CD templates.
+todos:
+  - id: scaffold-structure
+    content: Scaffold directory structure and starter artifacts
+    status: pending
+  - id: commands-rules
+    content: Add 10 commands and 4 rules with IO/stop gates
+    status: pending
+  - id: skills-agents
+    content: Create gsd-team skill, templates, and 6 agents
+    status: pending
+  - id: hooks-cicd-docs
+    content: Implement hooks, CI/CD workflows, and README updates
+    status: pending
+isProject: false
+---
+
+# Cursor-GSD-Team Kit Plan
+
+## Scope Summary
+
+Build a drop-in template repo that implements the full GSD workflow (intake → discovery → architecture → sprint plan → execute → QA → release → pause/resume) using Cursor-native artifacts: commands, rules, skills, subagents, hooks, docs, and GitHub Actions. Voice input is documented as an input layer only. CI/CD is template-based and driven by runbook keys.
+
+## Key Files and Structures
+
+- Template structure per spec: [.cursor/](.cursor/), [docs/](docs/), [sprints/](sprints/), [handoffs/](handoffs/), [decisions/](decisions/), [.github/workflows/](.github/workflows/)
+- Commands: `.cursor/commands/gsd-*.md` (10 commands)
+- Rules: `.cursor/rules/gsd-*.mdc` (4 rules)
+- Skills: `.cursor/skills/gsd-team/SKILL.md` + `templates/*.md`
+- Agents: `.cursor/agents/*.mdc` (PO, tech-lead, dev, QA, release, curator)
+- Hooks: `.cursor/hooks.json`, `.cursor/hooks/gsd-hook.py`, `.cursor/scratchpad.md`
+- Docs templates: `docs/product/*.md`, `docs/engineering/*.md`, `sprints/S0001/*`, `handoffs/*.md`, `decisions/DEC-0001.md`
+- CI/CD: `.github/workflows/ci.yml`, `.github/workflows/deploy.yml`
+- README updates: voice options + runbook usage
+
+## Implementation Outline
+
+1. **Scaffold repo layout** per section 4 and add starter artifacts in `docs/`, `sprints/`, `handoffs/`, `decisions/`.
+2. **Write 10 commands** in `.cursor/commands/` with explicit inputs/outputs, stop-conditions, and role usage.
+3. **Define rules** in `.cursor/rules/` for phase flow, quality gates, handoffs/state persistence, and escalation.
+4. **Create the skill** in `.cursor/skills/gsd-team/` and template files for story/acceptance/architecture/decision/sprint/handoff.
+5. **Define 6 subagents** with required IO and artifact persistence requirements.
+6. **Implement hooks** (`hooks.json` + dispatcher script) with fail-open logic, context-refresh checks, and safe-command blocking.
+7. **Add CI/CD workflows** that read `docs/engineering/runbook.md` keys and conditionally execute commands.
+8. **Update README** to document quick start, voice input strategies, and runbook-driven CI/CD.
+
+## Notes / Constraints
+
+- Voice input is documented only; no runtime integration beyond documentation.
+- Hooks and CI/CD must be fail-open unless commands are explicitly set.
+- Decision gate should create `decisions/DEC-xxxx.md` and stop until user decision.
+
+## Reference (Plan Spec)
+
+Primary source: [Plan.md](Plan.md)

package/.cursor/remote.json

@@ -0,0 +1,18 @@
+{
+  "servers": [
+    {
+      "name": "local-docker",
+      "type": "docker",
+      "host": "unix:///var/run/docker.sock",
+      "notes": "Example Docker socket configuration"
+    },
+    {
+      "name": "remote-ssh",
+      "type": "ssh",
+      "host": "example.com",
+      "port": 22,
+      "user": "ubuntu",
+      "notes": "Example SSH configuration"
+    }
+  ]
+}

package/.cursor/rules/gsd-core.mdc

@@ -0,0 +1,18 @@
+---
+description: "GSD core workflow and context pack rules"
+globs: ["**/*"]
+---
+
+- Use the GSD phase flow: intake -> discovery -> research -> architecture ->
+  sprint plan -> plan verify -> execute -> QA -> verify work -> release ->
+  refresh context.
+- `AUTO_FLOW_MODE` controls whether phases run automatically or stop at
+  decision gates (`auto_until_decision` recommended).
+- `PHASE_MODE=interactive` means ask questions; `PHASE_MODE=auto` minimizes
+  prompts unless decisions are required.
+- Persist decisions and state in files; do not keep critical info only in chat.
+- Pause/resume is first-class. Update `handoffs/resume_brief.md` on pause.
+- Context pack must stay compact: summarize, do not dump raw logs.
+- If `REMOTE_EXECUTION=1` and `.cursor/remote.json` is configured, the agent
+  may use the configured remote/docker servers for builds/tests.
+

package/.cursor/rules/gsd-escalation.mdc

@@ -0,0 +1,11 @@
+---
+description: "Decision gate and escalation logic"
+globs: ["**/*"]
+---
+
+- Trigger a decision when scope, security, data migration, or architecture
+  changes are high impact or unclear.
+- Create `decisions/DEC-xxxx.md` with 2-3 options and a recommendation.
+- Pause execution until a decision is made and recorded in
+  `docs/engineering/decisions.md`.
+

package/.cursor/rules/gsd-handoffs.mdc

@@ -0,0 +1,10 @@
+---
+description: "Handoffs and artifact persistence"
+globs: ["**/*"]
+---
+
+- Every role writes handoffs to files; nothing important stays in chat only.
+- Update sprint `summary.md` and `progress.md` after task completion.
+- Use `handoffs/*.md` for role-to-role transfers.
+- Keep `docs/engineering/state.md` current and concise.
+

package/.cursor/rules/gsd-quality.mdc

@@ -0,0 +1,15 @@
+---
+description: "Quality gates and small-step execution"
+globs: ["**/*"]
+---
+
+- Prefer small, atomic changes tied to a single task.
+- Run tests, lint, and typecheck when commands are configured.
+- If `AUTO_INSTALL_DEPS=1` in `.cursor/scratchpad.md`, install required
+  runtimes/libs without asking (package manager only).
+- If `AUTO_RELEASE_NOTES=1` in `.cursor/scratchpad.md`, generate release notes
+  automatically (scripted).
+- If `PERMISSION_MODE=auto`, do not ask for routine permission prompts.
+- Update `docs/engineering/state.md` after meaningful changes.
+- If tests fail and commands are set, fix or document before proceeding.
+

package/.cursor/scratchpad.md

@@ -0,0 +1,34 @@
+# GSD scratchpad
+#
+# Core behavior
+# - GSD_CONTEXT_STRICT: 0|1 (require context refresh after code changes)
+# - LOOP_UNTIL_GREEN: 0|1 (optional test loop)
+# - RUN_TESTS_ON_EDIT: 0|1 (run tests after edits)
+# - DONE: 0|1 (stop hook loops)
+GSD_CONTEXT_STRICT=1
+LOOP_UNTIL_GREEN=0
+RUN_TESTS_ON_EDIT=0
+DONE=0
+#
+# Benchmarking
+# - GSD_BENCH_SESSION: free-form id for live benchmark logging
+GSD_BENCH_SESSION=
+#
+# Automation
+# - AUTO_FLOW_MODE: manual|auto_until_decision
+# - PHASE_MODE: interactive|auto
+# - PERMISSION_MODE: interactive|auto
+# - AUTO_INSTALL_DEPS: 0|1
+# - AUTO_RELEASE_NOTES: 0|1
+AUTO_FLOW_MODE=manual
+PHASE_MODE=interactive
+PERMISSION_MODE=interactive
+AUTO_INSTALL_DEPS=0
+AUTO_RELEASE_NOTES=0
+#
+# Remote execution
+# - REMOTE_EXECUTION: 0|1
+# - REMOTE_CONFIG: path to remote config
+REMOTE_EXECUTION=0
+REMOTE_CONFIG=.cursor/remote.json
+

package/.cursor/skills/gsd-team/SKILL.md

@@ -0,0 +1,39 @@
+# GSD Team Skill
+
+This skill guides the AI dev team through the GSD workflow. It enforces
+artifact persistence, clear handoffs, and compact context packs.
+
+## Workflow
+
+1. Intake: clarify idea, write story + acceptance.
+2. Discovery: capture design/UX references.
+3. Research: summarize patterns, risks, dependencies.
+4. Architecture: define approach, risks, decisions.
+5. Sprint plan: create sprint and tasks.
+6. Plan verify: verify tasks cover acceptance.
+7. Execute: implement task-by-task, update state.
+8. QA: test plan, findings, verification.
+9. Verify work: UAT and user-facing validation.
+10. Release: notes, runbook, readiness.
+11. Refresh context: compact state + decisions.
+
+Optional modes:
+- Quick: fast path for small tasks.
+- Milestones: group phases into larger delivery cycles.
+
+## Required artifacts
+
+- `docs/product/*`
+- `docs/engineering/*`
+- `sprints/Sxxxx/*`
+- `sprints/quick/*`
+- `milestones/*`
+- `handoffs/*`
+- `decisions/*`
+
+## Templates
+
+Use templates in `templates/` for both markdown and JSON artifacts. JSON
+templates are preferred for structured data (story, acceptance, architecture,
+decision, sprint, handoff, plan-verify, UAT, milestone, phase context).
+

package/.cursor/skills/gsd-team/templates/acceptance.json

@@ -0,0 +1,10 @@
+{
+  "id": "US-0001",
+  "criteria": [
+    {
+      "id": "AC-1",
+      "text": "",
+      "done": false
+    }
+  ]
+}

package/.cursor/skills/gsd-team/templates/acceptance.md

@@ -0,0 +1,7 @@
+# Acceptance Criteria
+
+## US-0001
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+

package/.cursor/skills/gsd-team/templates/architecture.json

@@ -0,0 +1,11 @@
+{
+  "overview": "",
+  "components": [
+    {
+      "name": "",
+      "responsibility": ""
+    }
+  ],
+  "risks": [],
+  "decisions": []
+}

package/.cursor/skills/gsd-team/templates/architecture.md

@@ -0,0 +1,14 @@
+# Architecture
+
+## Overview
+- ...
+
+## Components
+- ...
+
+## Risks
+- ...
+
+## Decisions
+- Link to `decisions/DEC-xxxx.md`
+

package/.cursor/skills/gsd-team/templates/decision.json

@@ -0,0 +1,14 @@
+{
+  "id": "DEC-0001",
+  "status": "proposed",
+  "context": "",
+  "options": [
+    {
+      "id": "A",
+      "description": "",
+      "impact": ""
+    }
+  ],
+  "recommendation": "",
+  "impact": ""
+}

package/.cursor/skills/gsd-team/templates/decision.md

@@ -0,0 +1,19 @@
+# Decision
+
+ID: DEC-0001
+Status: Proposed
+
+## Context
+- ...
+
+## Options
+1. Option A
+2. Option B
+3. Option C
+
+## Recommendation
+- ...
+
+## Impact
+- ...
+

package/.cursor/skills/gsd-team/templates/handoff.json

@@ -0,0 +1,6 @@
+{
+  "from": "",
+  "to": "",
+  "summary": [],
+  "open_items": []
+}

package/.cursor/skills/gsd-team/templates/handoff.md

@@ -0,0 +1,12 @@
+# Handoff
+
+From:
+To:
+Date:
+
+## Summary
+- ...
+
+## Open items
+- ...
+

package/.cursor/skills/gsd-team/templates/milestone.json

@@ -0,0 +1,7 @@
+{
+  "id": "M0001",
+  "name": "",
+  "goal": "",
+  "scope": [],
+  "status": "active"
+}

package/.cursor/skills/gsd-team/templates/phase-context.json

@@ -0,0 +1,6 @@
+{
+  "phase": "intake",
+  "preferences": [],
+  "constraints": [],
+  "examples": []
+}

package/.cursor/skills/gsd-team/templates/plan-verify.json

@@ -0,0 +1,11 @@
+{
+  "sprint": "S0001",
+  "coverage": [
+    {
+      "acceptance_id": "AC-1",
+      "tasks": [],
+      "covered": false
+    }
+  ],
+  "gaps": []
+}

package/.cursor/skills/gsd-team/templates/sprint.json

@@ -0,0 +1,6 @@
+{
+  "id": "S0001",
+  "goal": "",
+  "scope": [],
+  "risks": []
+}

package/.cursor/skills/gsd-team/templates/sprint.md

@@ -0,0 +1,11 @@
+# Sprint
+
+ID: S0001
+Goal:
+
+## Scope
+- ...
+
+## Risks
+- ...
+

package/.cursor/skills/gsd-team/templates/story.json

@@ -0,0 +1,9 @@
+{
+  "id": "US-0001",
+  "as_a": "",
+  "i_want": "",
+  "so_that": "",
+  "in_scope": [],
+  "out_of_scope": [],
+  "constraints": []
+}

package/.cursor/skills/gsd-team/templates/story.md

@@ -0,0 +1,15 @@
+# User Story
+
+ID: US-0001
+
+As a ...
+I want ...
+So that ...
+
+## Scope
+- In:
+- Out:
+
+## Constraints
+- ...
+

package/.cursor/skills/gsd-team/templates/uat.json

@@ -0,0 +1,15 @@
+{
+  "sprint": "S0001",
+  "steps": [
+    {
+      "id": "UAT-1",
+      "description": "",
+      "result": "pending",
+      "notes": ""
+    }
+  ],
+  "summary": {
+    "passed": 0,
+    "failed": 0
+  }
+}