ai-core-framework 0.1.0

package/core/workflows/feature-lifecycle.md

@@ -0,0 +1,347 @@
+# 🔄 Feature Lifecycle Workflow
+
+> From requirement to production. Strict Agile/Scrum flow.
+
+## Overview Diagram
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│                      FEATURE LIFECYCLE                               │
+└──────────────────────────────────────────────────────────────────────┘
+
+  Stakeholder              BA/PM              Tech Lead           Dev              QA             SM
+       │                    │                    │                 │                │              │
+       │ requirement        │                    │                 │                │              │
+       ├───────────────────▶│                    │                 │                │              │
+       │                    │ /analyze-req       │                 │                │              │
+       │                    │ creates TICKET     │                 │                │              │
+       │                    │ creates spec       │                 │                │              │
+       │                    │ state: DRAFT       │                 │                │              │
+       │                    │                    │                 │                │              │
+       │                    │ HANDOFF───────────▶│                 │                │              │
+       │                    │                    │ /groom-ticket   │                │              │
+       │                    │                    │ estimates       │                │              │
+       │                    │                    │ state: GROOMED  │                │              │
+       │                    │                    │                 │                │              │
+       │                    │                    │ /write-plan     │                │              │
+       │                    │                    │ creates plan    │                │              │
+       │                    │                    │                 │                │              │
+       │                    │◀───────────────────┤                 │                │              │
+       │                    │ DoR check          │                 │                │              │
+       │                    │ state: READY       │                 │                │              │
+       │                    │                    │                 │                │              │
+       │                    │                    │                 │                │ /plan-sprint │
+       │                    │                    │                 │                │   pulls      │
+       │                    │                    │                 │                │   ticket to  │
+       │                    │                    │                 │                │   sprint     │
+       │                    │                    │                 │                │              │
+       │                    │                    │                 │ /implement-task│              │
+       │                    │                    │                 │ state:         │              │
+       │                    │                    │                 │ IN_PROGRESS    │              │
+       │                    │                    │                 │                │              │
+       │                    │                    │                 │ TDD:           │              │
+       │                    │                    │                 │ - test first   │              │
+       │                    │                    │                 │ - implement    │              │
+       │                    │                    │                 │ - refactor     │              │
+       │                    │                    │                 │                │              │
+       │                    │                    │                 │ /create-pr     │              │
+       │                    │                    │                 │ state:         │              │
+       │                    │                    │                 │ IN_REVIEW      │              │
+       │                    │                    │                 │                │              │
+       │                    │                    │ /techlead-review│                │              │
+       │                    │                    │◀────────────────┤                │              │
+       │                    │                    │ approve / reject│                │              │
+       │                    │                    │                 │                │              │
+       │                    │                    │ /merge-pr       │                │              │
+       │                    │                    │ state: QA       │                │              │
+       │                    │                    │                 │                │              │
+       │                    │                    │                 │                │ /smoke-test  │
+       │                    │                    │                 │                │ verify AC    │
+       │                    │                    │                 │                │              │
+       │                    │                    │                 │                │ Pass? ──────▶│
+       │                    │                    │                 │                │              │
+       │                    │                    │                 │                │              │ /release
+       │                    │                    │                 │                │              │ state: DONE
+```
+
+---
+
+## Phase 1: Requirement Intake
+
+**Owner**: `business-analyst` agent
+**Input**: Free text from stakeholder (email, Slack, voice transcript, Figma)
+**Output**: Ticket JSON with state `DRAFT` and linked spec in `docs/project/specs/`
+
+### Steps
+1. User invoke: `/analyze-requirements "I want users to reset passwords by email"`
+2. BA agent:
+   - Check 5W1H (Who/What/Why/When/Where/How)
+   - If information is missing → ask user and do not create ticket
+   - Classify: feature / enhancement / bug / tech-debt
+   - If bug → assign severity (SEV-1/2/3/4)
+3. BA writes User Story (INVEST)
+4. BA writes ≥3 AC scenarios (Gherkin)
+5. BA creates `docs/project/specs/TICKET-XXX-<slug>.md`
+6. BA creates `project/tickets/TICKET-XXX.json` with `spec_path`
+7. BA output HANDOFF → tech-lead
+
+### Gates
+- ✅ User Story pass INVEST
+- ✅ Has ≥3 AC scenarios
+- ✅ Business value is clear
+
+### Timeboxed
+Each requirement should finish in one session (< 30 minutes of BA work).
+
+---
+
+## Phase 2: Grooming
+
+**Owner**: `tech-lead` agent (primary), `business-analyst` (consult)
+**Input**: Ticket with state `DRAFT`
+**Output**: Ticket with state `GROOMED`
+
+### Steps
+1. User invoke: `/groom-ticket TICKET-XXX`
+2. Tech Lead:
+   - Read ticket + related code
+   - Identify technical approach
+   - Flag risks / unknowns
+   - Estimate story points (Fibonacci: 1, 2, 3, 5, 8, 13)
+   - If > 8 points → MUST split into sub-tickets
+3. If ambiguity exists → escalate back to BA
+4. Update ticket with `estimate`, technical notes, risks
+5. Transition state: DRAFT → GROOMED
+
+### Gates
+- ✅ Technical approach feasible
+- ✅ Estimate ≤ 8 points, or split
+- ✅ No critical unknowns
+
+---
+
+## Phase 2.5: Implementation Plan
+
+**Owner**: `tech-lead` agent
+**Input**: Ticket with state `GROOMED`
+**Output**: Linked implementation plan in `docs/project/plans/`
+
+### Steps
+1. User invoke: `/write-plan TICKET-XXX`
+2. Tech Lead:
+   - Read ticket and linked `spec_path`
+   - Inspect relevant code/docs enough to identify implementation boundaries
+   - Create `docs/project/plans/TICKET-XXX-<slug>-plan.md`
+   - Link ticket field `implementation_plan_path`
+   - Define tests, docs, verification, and rollback notes
+3. Suggest `/mark-ready TICKET-XXX`
+
+### Gates
+- ✅ Plan has concrete tasks
+- ✅ Test strategy defined
+- ✅ Documentation obligations identified
+- ✅ No production code modified
+
+---
+
+## Phase 3: Definition of Ready Check
+
+**Owner**: `scrum-master` agent
+**Input**: Ticket with state `GROOMED`
+**Output**: Ticket with state `READY`
+
+### DoR Checklist (from `rules/07-definition-of-ready.md`)
+- [ ] User Story pass INVEST
+- [ ] ≥3 AC scenarios (Gherkin)
+- [ ] Estimated (≤8 points)
+- [ ] Dependencies identified
+- [ ] Technical approach clear
+- [ ] Implementation plan linked when work is non-trivial
+- [ ] No blockers
+- [ ] Test strategy defined
+
+### Steps
+1. User invoke: `/mark-ready TICKET-XXX`
+2. SM run DoR checklist
+3. If pass → state: READY
+4. If fail → return to previous phase
+
+---
+
+## Phase 4: Sprint Planning
+
+**Owner**: `scrum-master` agent
+**Input**: Backlog of READY tickets
+**Output**: Sprint with selected tickets
+
+### Steps
+1. At sprint start, user invoke: `/plan-sprint`
+2. SM:
+   - Load all READY tickets
+   - Sort by priority (MUST > SHOULD > COULD)
+   - Pull tickets into sprint until capacity is reached (30 points default)
+   - Assign tickets to sprint
+3. Create `project/sprints/SPRINT-XXX.json`
+
+### Gates
+- ✅ Total points ≤ team capacity
+- ✅ All tickets state = READY
+- ✅ No sprint currently active
+
+---
+
+## Phase 5: Development (TDD)
+
+**Owner**: `developer` agent
+**Input**: Ticket with state `READY`, in active sprint
+**Output**: Ticket with state `IN_REVIEW`, PR created
+
+### Steps
+1. User invoke: `/implement-task TICKET-XXX`
+2. Dev agent:
+   - Run precondition checks
+   - Create branch: `feature/TICKET-XXX-slug`
+   - State transition: READY → IN_PROGRESS
+3. **TDD cycle** (strict):
+   - Write failing test for AC scenario 1
+   - Run test → must fail (red)
+   - Commit: `test(TICKET-XXX): add failing test for happy path`
+   - Write minimum code to pass
+   - Run test → must pass (green)
+   - Commit: `feat(TICKET-XXX): implement happy path`
+   - Refactor
+   - Commit: `refactor(TICKET-XXX): ...`
+   - Repeat for each AC scenario
+4. Coverage check: `/check-coverage` → must ≥80%
+5. Lint check
+6. Update docs if there is a new API
+7. Push branch
+8. State: IN_PROGRESS → ready for PR
+
+---
+
+## Phase 6: Code Review
+
+**Owner**: `developer` (create PR), `tech-lead` (review)
+**Input**: Ticket with implementation complete
+**Output**: Ticket with state `IN_REVIEW`, then approved
+
+### Steps
+1. Dev invoke: `/create-pr`
+2. System:
+   - Generate PR with template
+   - Auto-link ticket
+   - Auto-add test results, coverage
+   - State: → IN_REVIEW
+3. User invoke: `/techlead-review` (or SM auto-assigns)
+4. Tech Lead:
+   - Code quality
+   - Architecture alignment
+   - Security (OWASP checklist)
+   - Test adequacy
+   - Performance
+5. Outcome:
+   - **Approve** → next phase
+   - **Request changes** → back to Dev, state stays IN_REVIEW
+   - **Reject** → state back to IN_PROGRESS
+
+### Gates
+- ✅ All CI checks pass
+- ✅ Coverage ≥ 80% on diff
+- ✅ No critical security issues
+- ✅ Architecture aligned with ADRs
+
+---
+
+## Phase 7: Merge & QA
+
+**Owner**: `tech-lead` (merge), `qa-tester` (test)
+**Input**: Approved PR
+**Output**: Ticket with state `QA`, then `DONE`
+
+### Steps
+1. User invoke: `/merge-pr`
+2. System:
+   - Squash merge into develop
+   - Delete feature branch
+   - Deploy to staging
+   - State: IN_REVIEW → QA
+3. User invoke: `/smoke-test TICKET-XXX`
+4. QA agent:
+   - Verify each AC scenario on staging
+   - Exploratory testing
+   - Regression check
+5. Outcome:
+   - **Pass** → state: QA → DONE
+   - **Fail** → create bug ticket, link to feature, state back
+
+---
+
+## Phase 8: Release
+
+**Owner**: `scrum-master` agent
+**Input**: Multiple DONE tickets
+**Output**: Production deployment
+
+### Steps
+1. End of sprint: `/release v1.2.0`
+2. SM:
+   - Generate CHANGELOG from DONE tickets
+   - Create release/v1.2.0 branch
+   - Tag
+   - Deploy to production, or trigger CI
+   - Update all tickets: released_in = v1.2.0
+
+---
+
+## Special Paths
+
+### Hotfix Path (bypass sprint)
+
+```
+SEV-1 bug → /report-bug → /triage-bug (SEV-1 confirmed)
+    → /hotfix (bypass sprint planning)
+    → Fast track: implement → tech-lead review → merge → release to prod
+```
+
+See `workflows/hotfix-lifecycle.md`.
+
+### Blocked Path
+
+```
+Ticket hits blocker → state: BLOCKED
+    → Log blocker in comment
+    → Escalate to SM
+    → Khi unblock → return to previous state
+```
+
+---
+
+## Metrics Tracked
+
+Per ticket:
+- Lead time (DRAFT → DONE)
+- Cycle time (IN_PROGRESS → DONE)
+- Time in each state
+- Number of state transitions (measure churn)
+- Review iterations
+
+Per sprint:
+- Velocity (completed points)
+- Commitment vs. completion ratio
+- Scope change during sprint
+
+Dashboard: `/sprint-report`
+
+---
+
+## Anti-patterns (Will be flagged)
+
+❌ **Code without ticket**: Violates G-001
+❌ **Skip states**: Violates G-003
+❌ **Self-approval**: Violates G-008b
+❌ **Direct push to main**: Violates G-009c
+❌ **Disabled tests**: Violates G-011 (#6)
+❌ **Mid-sprint scope change** without explicit SM approval
+❌ **Cherry-pick merge** (squash merge is required)
+❌ **Long-lived branches** (>5 days without PR)

package/core/workflows/hotfix-lifecycle.md

@@ -0,0 +1,65 @@
+# Hotfix Lifecycle Workflow
+
+> Emergency path for production-impacting SEV-1 and SEV-2 issues.
+
+## 🎯 Purpose
+
+Restore production quickly while preserving traceability, review, QA verification, and follow-up work.
+
+## 🔄 Flow
+
+1. Incident confirmation
+   - Bug is reported with `/report-bug` or described directly to `/hotfix`.
+   - Tech Lead confirms severity and production impact.
+
+2. Incident ownership
+   - Assign incident owner.
+   - Identify communication channel.
+   - Record current production version and rollback option.
+
+3. Hotfix branch
+   - Branch from production source.
+   - Use `hotfix/BUG-XXX-slug` or `hotfix/TICKET-XXX-slug`.
+
+4. Minimal fix
+   - Reproduce issue.
+   - Add regression test if feasible.
+   - Implement smallest safe fix.
+   - Run targeted tests and security checks.
+
+5. Emergency review
+   - Open PR.
+   - Require Tech Lead approval.
+   - Require second reviewer if Tech Lead authored fix.
+
+6. Deploy and verify
+   - Merge and tag patch version.
+   - Deploy.
+   - QA verifies impacted production flow or approved pre-prod flow.
+
+7. Back-merge and follow-up
+   - Back-merge to `develop`.
+   - Create follow-up ticket for full DoD, root cause analysis, monitoring, and prevention.
+   - Write incident summary.
+
+## 🔒 Rules
+
+- Hotfix is only for urgent production incidents.
+- Minimal change only.
+- No direct push to protected branches.
+- Review still required.
+- Back-merge is mandatory.
+- Follow-up ticket is mandatory.
+
+## 📊 Artifacts
+
+- Bug report
+- Hotfix ticket if needed
+- Hotfix PR
+- Patch release record
+- Incident summary
+- Follow-up ticket
+
+## 🔗 Commands
+
+`/report-bug` → `/triage-bug` → `/hotfix` → `/create-pr` → `/techlead-review` → `/merge-pr` → `/verify-fix` → `/release` or patch deploy record

package/core/workflows/sprint-lifecycle.md

@@ -0,0 +1,56 @@
+# Sprint Lifecycle Workflow
+
+> End-to-end sprint process from backlog readiness to sprint report and retrospective.
+
+## 🎯 Purpose
+
+Ensure sprint commitments are realistic, tracked, and closed with factual metrics.
+
+## 🔄 Flow
+
+1. Backlog refinement
+   - BA creates `DRAFT` tickets with `/analyze-requirements`.
+   - Tech Lead grooms with `/groom-ticket`.
+   - Scrum Master verifies DoR with `/mark-ready`.
+
+2. Sprint planning
+   - Scrum Master runs `/validate-state`.
+   - Scrum Master runs `/plan-sprint`.
+   - Only `READY` tickets may be committed.
+
+3. Sprint execution
+   - Developer starts tickets with `/implement-task`.
+   - Developer creates PRs with `/create-pr`.
+   - Tech Lead reviews with `/techlead-review`.
+   - Tech Lead merges with `/merge-pr`.
+   - QA verifies with `/smoke-test`.
+
+4. Daily health check
+   - Review blocked tickets.
+   - Review IN_PROGRESS aging.
+   - Review IN_REVIEW and QA queues.
+   - Escalate blockers early.
+
+5. Sprint close
+   - Run `/sprint-report`.
+   - Mark completed, carryover, and cancelled work.
+   - Capture metrics and retrospective actions.
+
+## 🔒 Rules
+
+- No ticket enters sprint unless status is `READY`.
+- Capacity overcommit requires explicit human approval.
+- Scope changes require removed/added item record.
+- DONE requires QA verification.
+- Carryover is visible, not hidden.
+
+## 📊 Artifacts
+
+- `project/sprints/SPRINT-XXX.json`
+- `project/metrics/`
+- Retrospective notes
+- Sprint report
+
+## 🔗 Commands
+
+`/analyze-requirements` → `/groom-ticket` → `/mark-ready` → `/plan-sprint` → `/implement-task` → `/create-pr` → `/techlead-review` → `/merge-pr` → `/smoke-test` → `/sprint-report`

package/lib/install-codex.js

@@ -0,0 +1,85 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+function listFiles(rootDir) {
+  const files = [];
+
+  function walk(currentDir) {
+    for (const entry of fs.readdirSync(currentDir, { withFileTypes: true })) {
+      const absolutePath = path.join(currentDir, entry.name);
+
+      if (entry.isDirectory()) {
+        walk(absolutePath);
+      } else if (entry.isFile()) {
+        files.push(absolutePath);
+      }
+    }
+  }
+
+  walk(rootDir);
+  return files;
+}
+
+async function installCodex({ targetDir = process.cwd(), sourceCoreDir, confirm }) {
+  if (!sourceCoreDir) {
+    throw new Error('sourceCoreDir is required');
+  }
+
+  if (!fs.existsSync(sourceCoreDir) || !fs.statSync(sourceCoreDir).isDirectory()) {
+    throw new Error(`Source core directory not found: ${sourceCoreDir}`);
+  }
+
+  const targetCodexDir = path.join(targetDir, '.codex');
+  const stats = {
+    copied: 0,
+    skipped: 0,
+    overwritten: 0,
+    targetDir: targetCodexDir,
+  };
+
+  fs.mkdirSync(targetCodexDir, { recursive: true });
+
+  for (const sourceFile of listFiles(sourceCoreDir)) {
+    const relativePath = path.relative(sourceCoreDir, sourceFile);
+    const targetFile = path.join(targetCodexDir, relativePath);
+    let shouldCopy = true;
+    let overwriting = false;
+
+    if (fs.existsSync(targetFile)) {
+      const answer = confirm
+        ? await confirm(`Overwrite existing ${path.relative(targetDir, targetFile)}?`)
+        : 'skip';
+
+      if (answer === 'cancel') {
+        throw new Error('Installation cancelled');
+      }
+
+      if (answer !== 'overwrite') {
+        stats.skipped += 1;
+        shouldCopy = false;
+      } else {
+        overwriting = true;
+      }
+    }
+
+    if (!shouldCopy) {
+      continue;
+    }
+
+    fs.mkdirSync(path.dirname(targetFile), { recursive: true });
+    fs.copyFileSync(sourceFile, targetFile);
+    fs.chmodSync(targetFile, fs.statSync(sourceFile).mode);
+
+    if (overwriting) {
+      stats.overwritten += 1;
+    } else {
+      stats.copied += 1;
+    }
+  }
+
+  return stats;
+}
+
+module.exports = {
+  installCodex,
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "ai-core-framework",
+  "version": "0.1.0",
+  "description": "Chat-first enterprise AI SDLC framework installer for AI coding CLIs.",
+  "license": "MIT",
+  "author": {
+    "name": "AI Core"
+  },
+  "keywords": [
+    "sdlc",
+    "enterprise",
+    "agentic-workflow",
+    "agile",
+    "governance",
+    "codex"
+  ],
+  "bin": {
+    "ai-core-framework": "bin/ai-core-framework.js"
+  },
+  "files": [
+    "bin/",
+    "core/",
+    "lib/",
+    "README.md",
+    ".codex-plugin/",
+    ".claude-plugin/",
+    ".cursor-plugin/"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "pack:dry-run": "npm pack --dry-run"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}