ai-core-framework 0.1.0

package/core/skills/development-implement-task/SKILL.md

@@ -0,0 +1,308 @@
+---
+name: development-implement-task
+description: Use when the user asks to run /implement-task, implement a READY or IN_PROGRESS ticket, start feature work from a ticket, or code against acceptance criteria in AI Core.
+command: /implement-task
+display_name: "Implement Task"
+version: 1.0.0
+owner_agent: developer
+requires_agents:
+  - developer       # Main executor
+  - tech-lead       # Consult when architecture decision is required
+model_preference: sonnet  # Fast for coding
+args:
+  - name: ticket_id
+    required: true
+    format: "TICKET-XXX"
+    description: "Ticket ID from project/tickets/"
+preconditions:
+  - ticket_exists: "project/tickets/${ticket_id}.json"
+  - ticket_status_in: [READY, IN_PROGRESS]
+  - ticket_has_acceptance_criteria: true
+  - no_uncommitted_changes_on_main: true
+  - current_branch_matches: "feature/${ticket_id}-* OR creates new branch"
+postconditions:
+  - ticket_status: IN_PROGRESS
+  - branch_exists: "feature/${ticket_id}-*"
+  - unit_tests_written: true
+  - coverage_threshold: ">=80%"
+  - commit_messages_conventional: true
+---
+
+# /implement-task
+
+> Implement a ticket following strict Agile workflow. Main workhorse command.
+
+## 🎯 Purpose
+
+When Developer agent receives a READY ticket, this command:
+1. Validate the ticket is eligible to start
+2. Create feature branch with required convention
+3. Implement theo TDD (test first, code after)
+4. Run tests + coverage check
+5. Commit with Conventional Commits format
+6. Update ticket state → IN_REVIEW when complete
+
+## 🚦 Trigger
+
+**Manual**: User types `/implement-task TICKET-123`
+
+**Auto**: No auto-trigger. Explicit invocation is required.
+
+## 📋 Preconditions (STRICT - ABORT if fail)
+
+Before starting, the AI **MUST** check every condition below. If any condition fails, **ABORT** with a clear error message.
+
+### 1. Ticket exists
+```bash
+test -f "project/tickets/${TICKET_ID}.json" || ABORT "Ticket not found"
+```
+
+### 2. Ticket status valid
+Read `state.status` from ticket JSON. It **MUST** be `READY` or `IN_PROGRESS`.
+- If `DRAFT` → ABORT, suggest `/groom-ticket ${TICKET_ID}`
+- If `DONE` → ABORT, ticket is already closed
+- If `BLOCKED` → ABORT, show blocker
+
+### 3. Acceptance Criteria exists
+Ticket **MUST** have an `acceptance_criteria` array with ≥1 scenario. If not → ABORT, suggest `/analyze-requirements`.
+
+### 4. Git clean state
+```bash
+git status --porcelain | grep -q . && ABORT "Working directory not clean. Commit or stash changes first."
+```
+
+### 5. Current branch check
+- If currently on `main`/`master`/`develop` → create new feature branch
+- If currently on feature branch for a **different ticket** → ABORT, suggest switch
+- If currently on feature branch for **this ticket** → continue
+
+### 6. Definition of Ready check
+Load `rules/07-definition-of-ready.md`. Verify the ticket passes every item. If not → ABORT.
+
+## 🔄 Execution Flow (STRICT ORDER)
+
+```
+┌─────────────────────────────────────────────────┐
+│  STEP 1: Validate preconditions                 │
+│  → If any fail: ABORT with clear error          │
+├─────────────────────────────────────────────────┤
+│  STEP 2: Load context                           │
+│  → Read ticket JSON                             │
+│  → Read acceptance criteria                     │
+│  → Read related code (if ticket references it)  │
+│  → Read core/rules/02-code-quality.md       │
+│  → Read core/rules/05-testing-mandatory.md  │
+├─────────────────────────────────────────────────┤
+│  STEP 3: Create/checkout branch                 │
+│  → Branch name: feature/${TICKET_ID}-${slug}    │
+│  → Slug = kebab-case from ticket title            │
+│  → Example: feature/TICKET-123-reset-password   │
+├─────────────────────────────────────────────────┤
+│  STEP 4: Update ticket status → IN_PROGRESS     │
+│  → Update project/tickets/${TICKET_ID}.json       │
+│  → Add started_at timestamp                     │
+│  → Add assignee = "developer-agent"             │
+├─────────────────────────────────────────────────┤
+│  STEP 5: TDD - Write tests FIRST                │
+│  → For each AC scenario → write failing test    │
+│  → Run tests → MUST fail (red)                  │
+│  → Commit: "test(TICKET-XXX): add failing tests"│
+├─────────────────────────────────────────────────┤
+│  STEP 6: Implement minimum code to pass         │
+│  → Code to AC. Do not over-engineer            │
+│  → Run tests → MUST pass (green)                │
+│  → Commit: "feat(TICKET-XXX): implement ..."    │
+├─────────────────────────────────────────────────┤
+│  STEP 7: Refactor                               │
+│  → Clean up, DRY, SOLID                         │
+│  → Tests must still pass                        │
+│  → Commit: "refactor(TICKET-XXX): ..."          │
+├─────────────────────────────────────────────────┤
+│  STEP 8: Coverage check                         │
+│  → Run /check-coverage                          │
+│  → MUST >= 80% (or threshold in config)    │
+│  → If fail → return to STEP 5                   │
+├─────────────────────────────────────────────────┤
+│  STEP 9: Lint & format                          │
+│  → Run project's lint command                   │
+│  → MUST pass with 0 errors                      │
+│  → Warnings are allowed but MUST be logged                   │
+├─────────────────────────────────────────────────┤
+│  STEP 10: Security quick check                  │
+│  → No hardcoded secrets                    │
+│  → No console.log/print debug             │
+│  → No TODO/FIXME without ticket          │
+├─────────────────────────────────────────────────┤
+│  STEP 11: Update documentation                  │
+│  → If there is a new API → update docs/project/api/            │
+│  → If there is a breaking change → update CHANGELOG    │
+├─────────────────────────────────────────────────┤
+│  STEP 12: Final commit + push                   │
+│  → git push -u origin feature/${TICKET_ID}-...  │
+├─────────────────────────────────────────────────┤
+│  STEP 13: Update ticket → READY_FOR_REVIEW      │
+│  → Add implementation_notes                     │
+│  → Add self_review_checklist                    │
+│  → Add suggested_reviewer: "tech-lead"          │
+├─────────────────────────────────────────────────┤
+│  STEP 14: HANDOFF                               │
+│  → Suggest next command: /create-pr             │
+└─────────────────────────────────────────────────┘
+```
+
+## 🔒 Hard Rules (MUST follow)
+
+### RULE IT-001: TDD mandatory
+**MUST** write tests before code. If the user says "skip tests, code first", **REFUSE** and explain the rule.
+
+### RULE IT-002: No commit without test
+Every commit touching production code (`src/**`) **MUST** include corresponding tests, except pure refactor commits.
+
+### RULE IT-003: Conventional Commits
+Commit message **MUST** theo format:
+```
+<type>(TICKET-XXX): <short description>
+
+[optional body]
+
+[optional footer]
+```
+Types: `feat`, `fix`, `test`, `refactor`, `docs`, `chore`, `perf`, `style`.
+
+### RULE IT-004: Branch naming
+Branch name **MUST** match regex: `^(feature|bugfix|hotfix)/TICKET-\d+-[a-z0-9-]+$`
+
+### RULE IT-005: No scope creep
+**MUST NOT** implement anything outside ticket AC. If additional work is required, create a new ticket and document it in the current ticket.
+
+### RULE IT-006: Atomic commits
+Every commit = 1 logical change. Random "WIP" commits are **FORBIDDEN**.
+
+### RULE IT-007: Coverage threshold
+Coverage on **new code** (diff coverage) **MUST** be ≥ 80%. Overall coverage may be lower.
+
+### RULE IT-008: No direct push to protected branches
+**MUST NOT** push directly to `main`, `master`, `develop`, `release/*`. Only push feature branches.
+
+### RULE IT-009: Escalation on ambiguity
+If AC ambiguity or missing AC is discovered while coding, **STOP**, update ticket with `clarification_needed`, invoke BA agent.
+
+### RULE IT-010: Max scope
+If ticket estimate > 5 story points or > 2 days of work, **SPLIT** into sub-tickets before implementation.
+
+## 📥 Expected Inputs
+
+- `ticket_id` (required): Format `TICKET-XXX`
+
+## 📤 Expected Outputs
+
+### Success
+```markdown
+✅ TICKET-XXX implementation complete
+
+**Branch**: feature/TICKET-XXX-short-slug
+**Commits**: 7
+**Files changed**: 12
+**Coverage**: 85% (+3% from main)
+**Tests**: 23 added, all passing
+**Lint**: ✓ passed
+
+### Self-review checklist
+- [x] All AC scenarios implemented
+- [x] Unit tests cover happy + edge + error cases
+- [x] No TODO/FIXME without ticket reference
+- [x] Docs updated
+- [x] Conventional commits used
+
+### Next steps
+Run: `/create-pr`
+
+### HANDOFF → tech-lead
+Ready for review. Key things to verify:
+- [Specific concern 1]
+- [Specific concern 2]
+```
+
+### Failure
+```markdown
+❌ /implement-task ABORTED
+
+**Reason**: [Specific reason]
+**Precondition failed**: [Which one]
+**Suggested action**: [Next command to run]
+```
+
+## 🚨 Failure Modes & Recovery
+
+| Scenario | Action |
+|----------|--------|
+| Tests keep failing after 3 iterations | STOP, escalate to tech-lead |
+| Coverage not reached after 2 attempts | STOP, check whether AC is not testable |
+| Architecture issue found | STOP, invoke tech-lead for ADR |
+| Ticket is bigger than estimate | STOP, suggest split, escalate to SM |
+| Dependency conflict | STOP, escalate to tech-lead |
+| Security concern found | STOP, invoke tech-lead security review |
+
+## 🔗 Related Commands
+
+- **Before**: `/groom-ticket`, `/analyze-requirements`
+- **After**: `/create-pr`, `/techlead-review`
+- **Utility**: `/check-coverage`, `/run-tests`
+
+## 📊 Metrics Tracked
+
+After each run, log to `project/metrics/implement-task.jsonl`:
+
+```json
+{
+  "ticket_id": "TICKET-123",
+  "started_at": "2026-04-18T10:00:00Z",
+  "completed_at": "2026-04-18T12:30:00Z",
+  "duration_minutes": 150,
+  "commits": 7,
+  "lines_added": 234,
+  "lines_removed": 45,
+  "coverage_delta": 3.2,
+  "tests_added": 23,
+  "aborts": 0
+}
+```
+
+## 💡 Examples
+
+### Example 1: Happy path
+```
+User: /implement-task TICKET-042
+
+AI: Loading TICKET-042...
+✓ Preconditions passed
+✓ Created branch: feature/TICKET-042-reset-password-email
+✓ Ticket status: READY → IN_PROGRESS
+
+Step 5: Writing failing tests for AC scenarios...
+[writes test file]
+[runs tests → 3 failing, as expected ✓]
+[commits: "test(TICKET-042): add failing tests for password reset"]
+
+Step 6: Implementing...
+[writes src/auth/reset-password.ts]
+[runs tests → all 3 pass ✓]
+[commits: "feat(TICKET-042): implement password reset via email"]
+
+...
+
+✅ Complete. Run /create-pr next.
+```
+
+### Example 2: Abort (no AC)
+```
+User: /implement-task TICKET-099
+
+AI: ❌ ABORTED
+Reason: TICKET-099 has no acceptance criteria
+Suggested: Run /analyze-requirements TICKET-099 first
+```
+
+---
+**Last updated**: 2026-04-18
+**Maintainer**: Tech Lead

package/core/skills/executing-ticket/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: executing-ticket
+description: Use when implementing an IN_PROGRESS ticket from an approved plan, coding against acceptance criteria, updating ticket state during development, or preparing implementation evidence.
+---
+
+# Executing Tickets
+
+Use this after `/implement-task TICKET-XXX` has moved a ticket to `IN_PROGRESS`.
+
+## Process
+
+1. Read the ticket.
+2. Read `spec_path` and `implementation_plan_path` when present.
+3. Confirm scope and affected files.
+4. Follow the plan task by task.
+5. Write or update tests before production code where practical.
+6. Run verification commands.
+7. Update docs evidence in the ticket.
+8. Suggest `/create-pr TICKET-XXX <pr_url>`.
+
+## Stop Conditions
+
+Stop and ask when:
+
+- the plan contradicts the codebase
+- verification repeatedly fails
+- the ticket lacks required acceptance criteria
+- implementation would exceed the approved scope

package/core/skills/git-branch-status/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: git-branch-status
+description: Use when the user asks to run /branch-status, summarize current Git branch state, inspect branch health, or report repository branch context.
+command: /branch-status
+display_name: "Branch Status"
+version: 1.0.0
+status: READY
+owner_agent: developer
+model_preference: sonnet
+args: []
+preconditions:
+  - git_repo_exists: true
+postconditions:
+  - branch_report_generated: true
+---
+
+# /branch-status
+
+> Reports current branch health, ticket linkage, divergence, and cleanup recommendations.
+
+## 🎯 Purpose
+
+Help agents understand where they are before changing code or creating PRs.
+
+## 🔄 Execution Flow
+
+1. Verify repository is a Git repo.
+2. Read current branch and protected branch config.
+3. Check branch naming convention.
+4. Extract ticket ID from branch if present.
+5. Compare with remote and base branch.
+6. Check working tree and staged changes.
+7. Report open PR if any.
+8. Suggest next safe action.
+
+## 🔒 Hard Rules
+
+- MUST NOT modify files or branches.
+- MUST warn when on protected branch.
+- MUST warn when branch ticket does not match active ticket.
+- MUST report uncommitted changes before recommending checkout or pull.
+
+## 📤 Outputs
+
+- Current branch
+- Clean/dirty state
+- Ahead/behind status
+- Linked ticket
+- PR status
+- Suggested next command
+
+## 🔗 Related Commands
+
+- `/scan-untracked`
+- `/cleanup-branches`
+- `/create-pr`

package/core/skills/git-cleanup-branches/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: git-cleanup-branches
+description: Use when the user asks to run /cleanup-branches, find stale Git branches, prepare branch cleanup, or apply a safe branch cleanup workflow.
+command: /cleanup-branches
+display_name: "Cleanup Branches"
+version: 1.0.0
+status: READY
+owner_agent: developer
+model_preference: sonnet
+args:
+  - name: mode
+    required: false
+    enum: [dry-run, apply]
+    default: dry-run
+preconditions:
+  - git_repo_exists: true
+  - working_tree_clean: true
+postconditions:
+  - stale_branch_report_generated: true
+---
+
+# /cleanup-branches
+
+> Identifies merged, stale, or invalid local branches and optionally deletes safe ones.
+
+## 🎯 Purpose
+
+Keep branch lists clean without risking active work.
+
+## 🔄 Execution Flow
+
+1. Verify clean working tree.
+2. Fetch remote pruning metadata.
+3. List local branches excluding protected branches.
+4. Classify branches as merged, remote-deleted, stale, active-ticket, or unsafe.
+5. For dry-run, print proposed deletes only.
+6. For apply, delete only branches classified safe.
+7. Report skipped branches with reasons.
+
+## 🔒 Hard Rules
+
+- Default mode MUST be dry-run.
+- MUST NOT delete current branch.
+- MUST NOT delete protected branches.
+- MUST NOT delete branches with unmerged commits.
+- MUST NOT delete branches linked to tickets not `DONE` or `CANCELLED`.
+
+## 📤 Outputs
+
+- Safe to delete branches
+- Unsafe branches and reasons
+- Commands that would run or did run
+
+## 🔗 Related Commands
+
+- `/branch-status`
+- `/scan-untracked`

package/core/skills/git-scan-untracked/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: git-scan-untracked
+description: Use when the user asks to run /scan-untracked, inspect untracked files in a Git repo, classify generated or accidental files, or prepare an untracked-file report.
+command: /scan-untracked
+display_name: "Scan Untracked Files"
+version: 1.0.0
+status: READY
+owner_agent: developer
+model_preference: sonnet
+args: []
+preconditions:
+  - git_repo_exists: true
+postconditions:
+  - untracked_report_generated: true
+---
+
+# /scan-untracked
+
+> Reviews untracked files and recommends add, ignore, or delete actions.
+
+## 🎯 Purpose
+
+Prevent accidental commits of secrets, build artifacts, generated files, or local-only files.
+
+## 🔄 Execution Flow
+
+1. Run Git untracked file listing.
+2. Classify files: source, tests, docs, generated, local config, secrets risk, dependency/build artifacts.
+3. Compare with `.gitignore`.
+4. Recommend action for each file.
+5. Suggest `.gitignore` additions where appropriate.
+
+## 🔒 Hard Rules
+
+- MUST NOT delete files automatically.
+- MUST flag `.env`, private keys, certificates, and credentials as blocking.
+- MUST prefer ignore rules for build artifacts and local editor files.
+- MUST ask before staging any file.
+
+## 📤 Outputs
+
+- File classification table
+- Risk warnings
+- Suggested `.gitignore` additions
+- Suggested `git add` commands
+
+## 🔗 Related Commands
+
+- `/branch-status`
+- `/create-pr`

package/core/skills/meta-generate-views/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: meta-generate-views
+description: Use when the user asks to run /generate-views, regenerate AI Core derived views, refresh project dashboards or summaries, or rebuild state-derived reporting files.
+command: /generate-views
+display_name: "Generate Views"
+version: 1.0.0
+status: READY
+owner_agent: scrum-master
+model_preference: sonnet
+args: []
+preconditions:
+  - ai_state_exists: true
+postconditions:
+  - views_generated: true
+---
+
+# /generate-views
+
+> Generates human-readable views from `project/` without changing canonical state.
+
+## 🎯 Purpose
+
+Help humans navigate many tickets without making duplicate sources of truth.
+
+## 🔄 Execution Flow
+
+1. Load `project/backlog/backlog.json`.
+2. Load tickets, bugs, sprints, and releases.
+3. Generate `project/views/backlog.md`.
+4. Generate `project/views/ready.md`.
+5. Generate `project/views/blocked.md`.
+6. Generate `project/views/by-epic.md`.
+7. Generate `project/views/by-sprint.md`.
+8. Generate `project/views/release-candidates.md`.
+9. Include generation timestamp and source files.
+
+## 🔒 Hard Rules
+
+- Generated views MUST NOT be edited as canonical state.
+- Views MUST reference ticket IDs, not copy full ticket details.
+- Regeneration MUST be safe and deterministic.
+- Missing source files MUST be reported.
+
+## 📤 Outputs
+
+- Generated view file list
+- Warning list
+- Suggested next commands
+
+## 🔗 Related Commands
+
+- `/backlog-status`
+- `/prioritize-backlog`
+- `/ticket-health`

package/core/skills/meta-request-log/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: meta-request-log
+description: Use when the user asks to run /request-log, inspect recent user requests, summarize project request history, or show entries from the AI Core user request log.
+command: /request-log
+display_name: "Request Log"
+version: 1.0.0
+owner_agent: scrum-master
+requires_agents:
+  - scrum-master
+model_preference: sonnet
+args:
+  - name: limit
+    required: false
+    type: number
+    default: 20
+    description: "Number of recent user requests to show"
+preconditions:
+  - user_request_log_exists: "project/user-requests.jsonl"
+postconditions:
+  - request_log_reported: true
+---
+
+# /request-log
+
+> Show recent user requests recorded in `project/user-requests.jsonl`.
+
+## 🎯 Purpose
+
+Give the user an auditable view of what they asked the AI to do.
+
+## 🚦 Trigger
+
+```text
+/request-log
+/request-log 50
+```
+
+## 🔄 Execution Flow
+
+1. Read `project/user-requests.jsonl`.
+2. Show the most recent N entries, default 20.
+3. Include timestamp, agent, detected command, ticket ID, and sanitized request text.
+4. If the log is missing, tell the user to run `/setup-project`.
+
+## 🔒 Hard Rules
+
+### RULE RL-001: Do not expose redacted values
+The command **MUST NOT** attempt to reconstruct secrets from `request_hash` or any redacted value.
+
+### RULE RL-002: Log is append-only
+Existing `project/user-requests.jsonl` entries **MUST NOT** be edited. Corrections require a new request entry.
+
+## 📤 Output Format
+
+```markdown
+## User Request Log
+
+| Time | Agent | Command | Ticket | Request |
+|------|-------|---------|--------|---------|
+| 2026-05-10T14:29:03Z | codex-agent | - | - | ... |
+```

package/core/skills/meta-sprint-report/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: meta-sprint-report
+description: Use when the user asks to run /sprint-report, generate a sprint report, summarize sprint state, or report sprint progress from AI Core project data.
+command: /sprint-report
+display_name: "Sprint Report"
+version: 1.0.0
+status: READY
+owner_agent: scrum-master
+model_preference: sonnet
+args:
+  - name: sprint_id
+    required: false
+    format: "SPRINT-XXX"
+preconditions:
+  - sprint_state_available: true
+postconditions:
+  - sprint_report_generated: true
+---
+
+# /sprint-report
+
+> Produces a factual sprint health and outcome report from `project/`.
+
+## 🎯 Purpose
+
+Give the team an auditable view of commitment, progress, blockers, carryover, defects, and delivery risks.
+
+## 🔄 Execution Flow
+
+1. Load target sprint or active sprint.
+2. Load tickets, bugs, metrics, and state history.
+3. Calculate committed points, done points, carryover, blocked count, cycle time, and defect counts.
+4. List work by state.
+5. Identify aging tickets and unresolved blockers.
+6. Summarize risks, decisions, and recommended next actions.
+7. Save report under `project/sprints/` or `project/metrics/` if requested.
+
+## 🔒 Hard Rules
+
+- MUST compute from state files where possible.
+- MUST label estimates when data is incomplete.
+- MUST NOT hide blocked or failed work.
+- MUST distinguish committed scope from added scope.
+
+## 📤 Outputs
+
+- Sprint goal
+- Capacity and velocity
+- Ticket state table
+- Blockers
+- Bugs and escaped defects
+- Carryover
+- Recommendations
+
+## 🔗 Related Commands
+
+- `/plan-sprint`
+- `/mark-ready`
+- `/release`