ai-core-framework 0.1.0

package/core/skills/planning-plan-sprint/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: planning-plan-sprint
+description: Use when the user asks to run /plan-sprint, create or update a sprint plan, select READY tickets by capacity, or assign tickets to a sprint.
+command: /plan-sprint
+display_name: "Plan Sprint"
+version: 1.0.0
+status: READY
+owner_agent: scrum-master
+requires_agents:
+  - scrum-master
+consults_agents:
+  - business-analyst
+  - tech-lead
+  - developer
+  - qa-tester
+model_preference: sonnet
+args:
+  - name: sprint_id
+    required: false
+    format: "SPRINT-XXX"
+    description: "Sprint ID to create or update"
+preconditions:
+  - state_valid: true
+  - ready_tickets_exist: true
+  - capacity_configured: true
+postconditions:
+  - sprint_plan_created: true
+  - selected_tickets_have_sprint_id: true
+  - capacity_not_exceeded_without_approval: true
+---
+
+# /plan-sprint
+
+> Creates an auditable sprint plan from READY tickets using capacity, priority, dependencies, and team availability.
+
+## 🎯 Purpose
+
+Build a realistic sprint commitment. It selects only `READY` tickets, respects configured sprint capacity, checks dependencies, and writes the sprint plan to `project/sprints/`.
+
+## 🚦 Trigger
+
+Manual at sprint planning:
+
+- `/plan-sprint`
+- `/plan-sprint SPRINT-008`
+
+## 📋 Preconditions, STRICT
+
+1. `config/project-config.yaml` exists.
+2. `/validate-state` passes.
+3. At least one ticket has status `READY`.
+4. Sprint capacity is configured under `scrum.sprint_capacity_points`.
+5. No selected ticket has unresolved blockers.
+6. Current active sprint is closed or explicitly being replanned.
+
+## 🔄 Execution Flow
+
+1. Load project config, tickets, bugs, and previous sprint metrics.
+2. Determine sprint ID, dates, capacity, and team availability.
+3. List eligible tickets with status `READY`.
+4. Remove tickets blocked by unresolved dependencies.
+5. Sort candidates by priority, dependency order, risk, and age.
+6. Select tickets until capacity is reached.
+7. Reserve capacity for bugs, review, QA, and operational work.
+8. Validate no selected ticket violates DoR.
+9. Write `project/sprints/SPRINT-XXX.json` with goal, dates, capacity, committed tickets, risks, and assumptions.
+10. Update selected tickets with `sprint_id`.
+11. Append planning metrics to `project/metrics/sprint-planning.jsonl`.
+12. Output sprint goal, commitment, risks, and handoffs.
+
+## 🔒 Hard Rules
+
+### RULE PS-001: Only READY tickets enter sprint
+Tickets in `DRAFT`, `GROOMED`, `IN_PROGRESS`, `IN_REVIEW`, `QA`, `DONE`, `BLOCKED`, or `CANCELLED` MUST NOT be newly committed.
+
+### RULE PS-002: Capacity must be respected
+Committed story points MUST NOT exceed configured capacity unless a human explicitly approves and the risk is recorded.
+
+### RULE PS-003: Dependencies determine order
+A ticket MUST NOT be selected before its `blocked_by` tickets are done or planned earlier with a clear sequence.
+
+### RULE PS-004: Sprint goal required
+Every sprint plan MUST include a concise business goal, not just a list of tickets.
+
+### RULE PS-005: QA and review capacity reserved
+The plan MUST reserve capacity for code review, QA, bug verification, and carryover.
+
+### RULE PS-006: Replanning must be explicit
+Mid-sprint scope changes require SM approval, reason, removed/added items, and impact.
+
+## 📤 Outputs
+
+Success includes:
+
+- Sprint ID and dates
+- Sprint goal
+- Capacity summary
+- Committed ticket list
+- Risks and dependency notes
+- Handoff to Developer for first `/implement-task`
+
+Failure includes:
+
+- Missing precondition
+- Tickets requiring `/mark-ready`
+- Capacity or dependency conflict
+
+## 🔗 Related Commands
+
+- Before: `/mark-ready`, `/sprint-report`
+- After: `/implement-task`, `/daily-standup`, `/sprint-report`
+- Utility: `/validate-state`

package/core/skills/planning-prioritize-backlog/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: planning-prioritize-backlog
+description: Use when the user asks to run /prioritize-backlog, rank backlog items, apply MoSCoW/RICE/manual prioritization, or update backlog ordering.
+command: /prioritize-backlog
+display_name: "Prioritize Backlog"
+version: 1.0.0
+status: READY
+owner_agent: business-analyst
+consults_agents:
+  - tech-lead
+  - scrum-master
+model_preference: opus
+args:
+  - name: strategy
+    required: false
+    enum: [moscow, rice, manual]
+    default: moscow
+preconditions:
+  - backlog_exists: "project/backlog/backlog.json"
+postconditions:
+  - backlog_order_updated: true
+---
+
+# /prioritize-backlog
+
+> Updates backlog ranking in `project/backlog/backlog.json` using MoSCoW, RICE, dependencies, and stakeholder input.
+
+## 🎯 Purpose
+
+Keep product priority separate from ticket detail state. The backlog file owns order. Ticket files own implementation detail and state history.
+
+## 🔄 Execution Flow
+
+1. Load backlog and ticket details.
+2. Validate all backlog ticket references exist.
+3. Apply chosen strategy: MoSCoW, RICE, or manual human-specified order.
+4. Consider dependencies and blocked tickets.
+5. Produce proposed rank changes.
+6. Ask for confirmation before writing.
+7. Update `rank`, `priority`, scoring notes, `updated_at`, and `updated_by`.
+8. Run `/generate-views`.
+
+## 🔒 Hard Rules
+
+- MUST NOT rewrite ticket AC or technical approach.
+- MUST preserve every backlog item unless user confirms removal.
+- MUST put blocked dependencies before dependent work.
+- MUST log rationale for major priority changes.
+
+## 📤 Outputs
+
+- New backlog order
+- Changed ranks
+- Priority rationale
+- Risk notes
+- Next command recommendations
+
+## 🔗 Related Commands
+
+- `/backlog-status`
+- `/generate-views`
+- `/plan-sprint`

package/core/skills/planning-write-plan/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: planning-write-plan
+description: Use when the user asks to run /write-plan, create an implementation plan for a groomed ticket, break down technical work, or prepare a ticket for development.
+command: /write-plan
+display_name: "Write Implementation Plan"
+version: 1.0.0
+status: READY
+owner_agent: tech-lead
+requires_agents:
+  - tech-lead
+consults_agents:
+  - developer
+  - qa-tester
+model_preference: opus
+args:
+  - name: ticket_id
+    required: true
+    format: "TICKET-XXX"
+preconditions:
+  - ticket_exists: true
+  - ticket_status_in:
+      - GROOMED
+      - READY
+postconditions:
+  - implementation_plan_created: true
+  - ticket_links_plan: true
+---
+
+# /write-plan
+
+> Create a detailed implementation plan in `docs/project/plans/` and link it from the ticket.
+
+## Purpose
+
+Turn a groomed or ready ticket into a concrete execution plan before coding starts. This gives AI agents exact scope, files, tests, docs, and verification steps.
+
+## Chat Usage
+
+```text
+/write-plan TICKET-001
+```
+
+## Execution Flow
+
+1. Read `project/tickets/TICKET-XXX.json`.
+2. Read `spec_path` if present.
+3. Inspect relevant code/docs just enough to identify affected files and test strategy.
+4. Create `docs/project/plans/TICKET-XXX-<slug>-plan.md`.
+5. Link the plan from the ticket as `implementation_plan_path`.
+6. Add a ticket comment noting the plan path.
+7. Validate state.
+8. Suggest `/implement-task TICKET-XXX`.
+
+## Hard Rules
+
+- MUST NOT modify production code.
+- MUST NOT create vague plan steps.
+- MUST include exact verification expectations where known.
+- MUST include documentation obligations.
+- MUST include rollback notes for risky behavior, migration, data, auth, billing, or deployment changes.
+- MUST stop and ask if the ticket is too ambiguous to plan.
+
+## Output
+
+- plan path
+- linked ticket
+- validation result
+- suggested next command

package/core/skills/project-detect-stack/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: project-detect-stack
+description: Use when the user asks to run /detect-stack, identify the project's technology stack, inspect dependencies and build tools, or propose project config updates from repository evidence.
+command: /detect-stack
+display_name: "Detect Stack"
+version: 1.0.0
+status: READY
+owner_agent: tech-lead
+model_preference: sonnet
+args: []
+preconditions:
+  - repository_readable: true
+postconditions:
+  - stack_report_generated: true
+  - project_config_update_proposed: true
+---
+
+# /detect-stack
+
+> Detect language, framework, package manager, database, test runner, and quality commands.
+
+## 🎯 Purpose
+
+Populate or validate `config/project-config.yaml` from actual repository evidence instead of guesses.
+
+## 🚦 Trigger
+
+- `/detect-stack`
+- Usually invoked during `/setup-project`
+
+## 📋 Preconditions, STRICT
+
+1. Run from project root.
+2. Repository files are readable.
+3. Do not modify config unless user approves or command is explicitly in update mode.
+
+## 🔄 Execution Flow
+
+1. Inspect dependency files such as `package.json`, `pnpm-lock.yaml`, `pyproject.toml`, `requirements.txt`, `go.mod`, `pom.xml`, `build.gradle`, `Cargo.toml`.
+2. Detect primary language and runtime.
+3. Detect framework from dependencies and folder structure.
+4. Detect package manager from lock files.
+5. Detect test runner, lint command, type check command, and build command.
+6. Detect database and infra dependencies from config, compose files, and env examples.
+7. Compare detected values with `project-config.yaml`.
+8. Output proposed config patch and confidence per field.
+9. If approved, update config and recommend `/sync-platforms`.
+
+## 🔒 Hard Rules
+
+### RULE DS-001: Evidence over assumptions
+Every detected field MUST cite evidence path or be marked `unknown`.
+
+### RULE DS-002: Do not invent commands
+Only list test/lint/build commands that exist in project config files or scripts.
+
+### RULE DS-003: Preserve manual config
+Do not overwrite user-defined config without explicit approval.
+
+## 📤 Outputs
+
+- Detected stack table
+- Confidence and evidence
+- Suggested config changes
+- Unknowns requiring user input
+
+## 🔗 Related Commands
+
+- `/setup-project`
+- `/discover-codebase`
+- `/sync-platforms`

package/core/skills/project-discover-codebase/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: project-discover-codebase
+description: Use when the user asks to run /discover-codebase, map an unfamiliar codebase, document architecture notes, inspect project structure, or gather repository context for AI Core.
+command: /discover-codebase
+display_name: "Discover Codebase"
+version: 1.0.0
+status: READY
+owner_agent: tech-lead
+model_preference: opus
+args: []
+preconditions:
+  - repository_readable: true
+  - stack_detected_or_known: true
+postconditions:
+  - codebase_map_generated: true
+  - architecture_notes_updated: true
+---
+
+# /discover-codebase
+
+> Build a concise map of modules, boundaries, data flow, test layout, and operational entry points.
+
+## 🎯 Purpose
+
+Give AI agents shared context before implementation and review. The output helps agents find the right files, understand architecture boundaries, and avoid accidental scope creep.
+
+## 🚦 Trigger
+
+- `/discover-codebase`
+- Recommended after `/detect-stack`
+
+## 📋 Preconditions, STRICT
+
+1. Repository is readable.
+2. Generated/vendor/build directories are excluded.
+3. Sensitive files such as `.env` are not read.
+
+## 🔄 Execution Flow
+
+1. Load `config/project-config.yaml`.
+2. Enumerate top-level directories and identify application, test, config, docs, scripts, and infra areas.
+3. Identify entry points, routes/controllers, domain modules, data access, jobs/workers, and shared libraries.
+4. Identify test layout and command coverage.
+5. Identify architecture docs and ADRs.
+6. Identify external integrations and environment assumptions.
+7. Produce `project/codebase-map.md` or update existing map with timestamp.
+8. List risks, missing docs, and recommended follow-up tickets.
+
+## 🔒 Hard Rules
+
+### RULE DC-001: Do not read secrets
+Never open `.env`, private keys, or credential files. Use `.env.example` only.
+
+### RULE DC-002: Do not modify production code
+Discovery is read-only except writing framework state/docs.
+
+### RULE DC-003: Keep map concise
+The map should help navigation, not duplicate source code.
+
+## 📤 Outputs
+
+- Module map
+- Entry points
+- Test map
+- Architecture notes
+- Integration list
+- Missing documentation risks
+
+## 🔗 Related Commands
+
+- `/setup-project`
+- `/detect-stack`
+- `/groom-ticket`
+- `/implement-task`

package/core/skills/project-setup-project/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: project-setup-project
+description: Use when the user asks to run /setup-project, initialize AI Core project state, review project config, sync platform configs, or prepare directories and logs for AI Core.
+command: /setup-project
+display_name: "Setup Project"
+version: 1.0.0
+status: READY
+owner_agent: scrum-master
+requires_agents:
+  - scrum-master
+consults_agents:
+  - tech-lead
+model_preference: sonnet
+args: []
+preconditions:
+  - ai_core_exists: true
+  - git_repo_exists: true
+postconditions:
+  - project_config_reviewed: true
+  - platform_configs_synced: true
+  - state_directories_created: true
+  - user_request_log_created: true
+  - hooks_install_recommended: true
+---
+
+# /setup-project
+
+> Initialize AI Core framework inside a project and prepare it for daily use.
+
+## 🎯 Purpose
+
+Make a copied `core/` framework operational in a real repository. This command checks repo structure, updates configuration, creates state directories, syncs platform instructions, and explains next steps.
+
+## 🚦 Trigger
+
+Manual after copying `core/` into a project:
+
+- `/setup-project`
+- `bash core/scripts/setup-project.sh`
+
+## 📋 Preconditions, STRICT
+
+1. Repository has `.git/`.
+2. `core/README.md` exists.
+3. `core/templates/project/project-config.yaml` exists.
+4. `core/templates/project/project-structure.yaml` exists.
+5. User has permission to create `config/`, `project/`, `docs/project/`, `docs/runtime/`, `.claude/`, `.cursor/`, `.windsurfrules`, and `CLAUDE.md`.
+
+## 🔄 Execution Flow
+
+1. Confirm repo root and `core/` location.
+2. Create `config/` if missing.
+3. Copy `core/templates/project/project-config.yaml` to `config/project-config.yaml` if missing.
+4. Copy `core/templates/project/project-structure.yaml` to `config/project-structure.yaml` if missing.
+5. Ask for missing project fields or infer with `/detect-stack`.
+6. Create required `project/` directories: tickets, backlog, bugs, sprints, releases, metrics, views, test-runs, verifications, incidents, prs.
+7. Create required docs namespaces: `docs/project/` for project/product requirements and `docs/runtime/` for operational AI Core documentation.
+8. Create `project/backlog/backlog.json` and `project/user-requests.jsonl` if missing.
+9. Run `bash core/scripts/setup-project.sh` when shell access is available, or perform steps 2-8 manually.
+10. Install root `scripts/` copies from canonical `core/scripts/` if they are missing.
+11. Install portable `.github/workflows/ai-core-governance.yml` if missing.
+12. Run `/sync-platforms` or `bash core/scripts/sync-platforms.sh`.
+13. Recommend installing hooks with `bash scripts/install-hooks.sh` if `.githooks/` exists.
+14. Run `/validate-state`.
+15. Output project readiness summary and first workflow suggestion.
+
+## 🔒 Hard Rules
+
+### RULE SP-001: Do not overwrite user config blindly
+If config values already exist, preserve them unless user confirms change.
+
+### RULE SP-002: Keep `core/` canonical
+Generated `.claude/`, `.cursor/`, and `.windsurfrules` files are exports. Source changes belong in `core/`.
+
+### RULE SP-003: No product code changes
+Setup modifies AI runtime/config files only: `config/`, `project/`, `docs/project/`, `docs/runtime/`, generated platform config, and optional docs scaffolding. It MUST NOT modify production source code.
+
+### RULE SP-004: State directories required
+A project is not ready until `project/` contains directories for tickets, backlog, bugs, sprints, releases, metrics, views, test-runs, verifications, incidents, and prs.
+
+### RULE SP-004a: User request log required
+A project is not ready until `project/user-requests.jsonl` exists. Every AI-handled user request **MUST** be logged there before substantive work begins.
+
+### RULE SP-005: `core` remains framework-only
+Project-specific state and config MUST NOT be written under `core/`. Use `project/` and `config/`.
+
+### RULE SP-006: `core/scripts` is canonical
+Portable enforcement scripts live under `core/scripts/`. Root `scripts/` entries are install-time copies for developer convenience.
+
+## 📤 Outputs
+
+Success:
+
+- Config status
+- User request log status
+- Detected stack summary
+- Generated platform files
+- Hook install recommendation
+- Next command: `/analyze-requirements` or `/discover-codebase`
+
+Failure:
+
+- Missing `core/`
+- Not a Git repository
+- Sync failure
+- Invalid config
+
+## 🔗 Related Commands
+
+- `/detect-stack`
+- `/discover-codebase`
+- `/sync-platforms`
+- `/validate-state`

package/core/skills/qa-bug-status/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: qa-bug-status
+description: Use when the user asks to run /bug-status, summarize bug state, report open/fixed/verified bugs, or inspect QA bug tracking data.
+command: /bug-status
+display_name: "Bug Status"
+version: 1.0.0
+status: READY
+owner_agent: qa-tester
+model_preference: sonnet
+args: []
+preconditions:
+  - bug_state_readable: true
+postconditions:
+  - bug_report_generated: true
+---
+
+# /bug-status
+
+> Summarizes open bugs by severity, priority, status, age, owner, and release impact.
+
+## 🎯 Purpose
+
+Give QA, Scrum Master, and Tech Lead a clear picture of defect health.
+
+## 🔄 Execution Flow
+
+1. Load `project/bugs/*.json`.
+2. Group bugs by severity and status.
+3. Identify stale bugs and missing owners.
+4. Identify release-blocking bugs.
+5. Summarize recent fixes awaiting verification.
+6. Recommend next commands.
+
+## 🔒 Hard Rules
+
+- MUST highlight SEV-1 and SEV-2 first.
+- MUST flag bugs without reproducer, owner, or priority.
+- MUST separate open bugs from verified/closed bugs.
+
+## 📤 Outputs
+
+- Bug count by severity
+- Bug count by status
+- Release blockers
+- Verification queue
+- Stale bugs
+
+## 🔗 Related Commands
+
+- `/report-bug`
+- `/triage-bug`
+- `/verify-fix`