ai-core-framework 0.1.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "ai-core",
+  "description": "Enterprise AI SDLC framework: chat-first workflow commands, role agents, project state, docs governance, and validation gates.",
+  "version": "0.1.0",
+  "author": {
+    "name": "AI Core"
+  },
+  "license": "MIT",
+  "keywords": [
+    "sdlc",
+    "enterprise",
+    "agents",
+    "workflow",
+    "governance",
+    "skills"
+  ],
+  "skills": "./core/skills/",
+  "agents": "./core/agents/",
+  "commands": "./core/commands/",
+  "hooks": "./hooks/hooks.json"
+}

package/.codex-plugin/plugin.json

@@ -0,0 +1,35 @@
+{
+  "name": "ai-core",
+  "version": "0.1.0",
+  "description": "Chat-first enterprise AI SDLC framework with agents, workflow commands, project state, docs governance, and validation gates.",
+  "author": {
+    "name": "AI Core"
+  },
+  "license": "MIT",
+  "keywords": [
+    "sdlc",
+    "enterprise",
+    "agentic-workflow",
+    "agile",
+    "governance",
+    "skills"
+  ],
+  "skills": "./core/skills/",
+  "interface": {
+    "displayName": "AI Core",
+    "shortDescription": "Enterprise AI SDLC workflow with tickets, docs, validation, and guided chat commands",
+    "longDescription": "Use AI Core to guide AI agents through requirement intake, grooming, implementation planning, development, review, QA, release governance, documentation enforcement, and project-state tracking.",
+    "developerName": "AI Core",
+    "category": "Coding",
+    "capabilities": [
+      "Interactive",
+      "Read",
+      "Write"
+    ],
+    "defaultPrompt": [
+      "Set up AI Core for this project.",
+      "Analyze this requirement and create a managed ticket."
+    ],
+    "brandColor": "#2563EB"
+  }
+}

package/.cursor-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "ai-core",
+  "displayName": "AI Core",
+  "description": "Enterprise AI SDLC framework: chat-first workflow commands, role agents, project state, docs governance, and validation gates.",
+  "version": "0.1.0",
+  "author": {
+    "name": "AI Core"
+  },
+  "license": "MIT",
+  "keywords": [
+    "sdlc",
+    "enterprise",
+    "agents",
+    "workflow",
+    "governance",
+    "skills"
+  ],
+  "skills": "./core/skills/",
+  "agents": "./core/agents/",
+  "commands": "./core/commands/",
+  "hooks": "./hooks/hooks-cursor.json"
+}

package/README.md

@@ -0,0 +1,173 @@
+
+## Install with npx
+
+AI Core can be installed into a project as an npm-powered CLI:
+
+```bash
+npx ai-core-framework
+```
+
+Run the command from the root of the project that should receive AI Core. The
+installer asks which AI CLI to target. Version 0.1 supports Codex and copies the
+contents of this repo's `core/` directory directly into the target project's
+`.codex/` directory:
+
+```text
+.codex/
+  agents/
+  config/
+  rules/
+  scripts/
+  skills/
+  templates/
+  workflows/
+  README.md
+```
+
+If a destination file already exists, the installer asks whether to overwrite,
+skip, or cancel. Pressing Enter at a conflict prompt skips the file.
+
+---
+
+## 📊 Phase 1 Status (2026-04-18)
+
+**10/10 Priority 1 files completed** — production-ready content.
+
+### Completed files (Phase 0 + Phase 1)
+
+**Agents** (all 5 complete):
+- ✅ business-analyst.md (Phase 0)
+- ✅ tech-lead.md (Phase 1)
+- ✅ developer.md (Phase 1)
+- ✅ qa-tester.md (placeholder, Phase 2)
+- ✅ scrum-master.md (placeholder, Phase 2)
+
+**Rules** (3/10 complete):
+- ✅ 00-global-rules.md (Phase 0)
+- ✅ 01-git-workflow.md (Phase 1)
+- ✅ 05-testing-mandatory.md (Phase 1)
+- ✅ 07-definition-of-ready.md (Phase 0)
+- ✅ 08-definition-of-done.md (Phase 0)
+- 📝 Others: placeholders (Phase 2+)
+
+**Commands** (5/15+ complete):
+- ✅ planning/analyze-requirements.md (Phase 1)
+- ✅ planning/groom-ticket.md (Phase 1)
+- ✅ development/implement-task.md (Phase 0)
+- ✅ review/create-pr.md (Phase 1)
+- ✅ review/techlead-review.md (Phase 1)
+- 📝 Others: placeholders (Phase 2+)
+
+**Templates** (2/4 complete):
+- ✅ pr/pull-request-template.md (Phase 1)
+- ✅ requirements/user-story-template.md (Phase 1)
+- 📝 Others: placeholders
+
+### Total content
+- **4,105 lines** of production-quality specification across Phase 1 files alone
+- All files follow consistent structure: YAML frontmatter, purpose, hard rules, flow, examples, metrics
+- Cross-references between files validated
+- Sync script tested & working
+
+---
+
+## 📊 Phase 2 Status (2026-04-18)
+
+**7/7 Priority 2 files completed** — QA flow + state enforcement.
+
+### Completed files (Phase 2)
+
+**Agents**:
+- ✅ qa-tester.md — Full QA agent (10 hard rules QA-001 to QA-010)
+
+**Commands**:
+- ✅ review/merge-pr.md — Merge gate (10 hard rules MP-001 to MP-010)
+- ✅ qa/smoke-test.md — Feature verification (10 hard rules SM-001 to SM-010)
+- ✅ qa/verify-fix.md — Bug fix verification (10 hard rules VF-001 to VF-010)
+- ✅ qa/report-bug.md — Bug filing (10 hard rules RB-001 to RB-010)
+
+**Rules**:
+- ✅ 06-approval-gates.md — State machine enforcement (10 hard rules AG-001 to AG-010)
+
+**Templates**:
+- ✅ qa/bug-report-template.md — Comprehensive bug template with severity justification
+
+### Total Phase 2 content
+- **3,002 lines** of production-quality specification
+- Full state machine documented with allowed/forbidden transitions
+- Complete happy path now covered: DRAFT → GROOMED → READY → IN_PROGRESS → IN_REVIEW → QA → DONE
+- Bug flow covered: report → triage → fix → verify
+
+### Combined Phase 1 + Phase 2 stats
+- **21 files production-ready** (~9,500 lines)
+- **All 5 agents complete** (BA, Tech Lead, Developer, QA, Scrum Master placeholder)
+- **9 commands complete** (analyze, groom, implement, create-pr, techlead-review, merge-pr, smoke-test, verify-fix, report-bug)
+- **6 rules complete** (global, git, testing, approval-gates, DoR, DoD)
+- **3 templates complete** (user story, PR, bug report)
+
+### Happy path E2E now possible:
+```
+BA: /analyze-requirements "Add feature X"
+   → creates TICKET-042 (DRAFT)
+Tech Lead: /groom-ticket TICKET-042
+   → DRAFT → GROOMED (estimated, risks identified)
+SM: /mark-ready TICKET-042  (Phase 3)
+   → GROOMED → READY
+Dev: /implement-task TICKET-042
+   → READY → IN_PROGRESS (TDD)
+Dev: /create-pr
+   → IN_PROGRESS → IN_REVIEW (quality gates passed)
+Tech Lead: /techlead-review 123
+   → approval or request changes
+Tech Lead: /merge-pr 123
+   → IN_REVIEW → QA (merged to develop)
+QA: /smoke-test TICKET-042
+   → QA → DONE (verified in staging)
+```
+
+## Enterprise Enforcement Additions
+
+The framework now includes mechanical gates beyond prompt-level rules:
+
+- `scripts/validate-state.sh` validates ticket state transitions, backlog rank integrity, dependency ordering, blocked-ticket unblock evidence, DONE-ticket DoD fields, QA evidence, and release governance records.
+- `scripts/validate-docs.sh` validates documentation obligations from diffs and ticket metadata, including API docs, README/setup docs, migration runbooks, ADRs, changelog/release notes, and DONE-ticket documentation evidence.
+- `scripts/validate-permissions.sh` validates state-history command execution against `core/commands/**` role metadata and blocks obvious self-approval.
+- `core/scripts/` is now the canonical portable script source. Root `scripts/` copies are installed for convenience by setup.
+- `core/scripts/ai-core.sh` is a lightweight command runner that checks command role metadata before dispatching executable handlers.
+- `core/scripts/workflow.sh` provides executable state-transition handlers for `/analyze-requirements`, `/groom-ticket`, `/mark-ready`, `/implement-task`, `/create-pr`, `/merge-pr`, `/smoke-test`, and `/release`.
+- `core/skills/` provides chat-first behavior guidance inspired by skill-based systems: AI Core bootstrap, brainstorming, implementation planning, ticket execution, and verification-before-done.
+- `/analyze-requirements` can create a linked spec in `docs/project/specs/`; `/write-plan` creates a linked implementation plan in `docs/project/plans/`.
+- `core/scripts/validate-audit-log.sh` validates the hash chain in `project/audit-log.jsonl`; executable workflow handlers append audit records.
+- `core/scripts/log-user-request.sh` appends every AI-handled user request to `project/user-requests.jsonl` so the user can review what they asked for.
+- `/request-log` shows recent entries from `project/user-requests.jsonl`.
+- `core/scripts/install-codex-prompts.sh` installs AI Core commands as Codex custom slash prompts in `~/.codex/prompts`.
+- `CODEOWNERS` adds review ownership defaults for `core/`, `config/`, `project/`, ADRs, runbooks, and workflows.
+- `config/docs-policy.json` can override documentation detection paths from `core/config/docs-policy.default.json`.
+- `.github/workflows/ai-core-governance.yml` is the portable governance workflow. App CI remains stack-specific and can be replaced with templates from `core/templates/ci/`.
+- `scripts/setup-project.sh` and `core/scripts/setup-project.sh` make copied `core/` installs executable: project config, runtime state folders, docs folders, backlog seed file, platform sync, and state validation.
+- `.github/workflows/ci.yml` and `.github/workflows/validate-state.yml` run AI Core governance checks in CI.
+- `.githooks/pre-commit` runs documentation gates before commit after hooks are installed with `bash scripts/install-hooks.sh`.
+- `core/config/release.schema.json` and `core/templates/release/release-record-template.json` define release approval, rollback, QA, security, and known-issue evidence.
+- `scripts/generate-views.sh` now produces dashboard and release readiness views in `project/views/`.
+
+Chat-first setup flow:
+
+```text
+/setup-project
+/validate-state
+/validate-docs
+/validate-permissions
+/generate-views
+/analyze-requirements "User can reset password"
+```
+
+Guided workflow mode:
+
+```text
+guide /analyze-requirements "User can reset password"
+next TICKET-001
+```
+
+The normal interface is the AI chat window. The AI should infer the correct role from command metadata (`owner_agent` / `requires_agents`) and may use `core/scripts/ai-core.sh` internally for deterministic execution and validation. Users should not need to type `bash ...` or `AI_AGENT=...`.
+
+`guide` runs one step, reports the completed command, ticket state before/after, updated `project` files, validation results, and the suggested next chat command. It asks before continuing and does not auto-run steps that still need placeholders such as `<story_points>` or `<pr_url>`.

package/bin/ai-core-framework.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+
+const fs = require('node:fs');
+const path = require('node:path');
+const readline = require('node:readline/promises');
+const { stdin, stdout } = require('node:process');
+
+const { installCodex } = require('../lib/install-codex');
+
+const packageRoot = path.resolve(__dirname, '..');
+const sourceCoreDir = path.join(packageRoot, 'core');
+
+function normalizeAnswer(answer) {
+  return answer.trim().toLowerCase();
+}
+
+async function askConflict(rl, question) {
+  const answer = normalizeAnswer(await rl.question(`${question} [skip/overwrite/cancel] `));
+
+  if (answer === 'o' || answer === 'overwrite') {
+    return 'overwrite';
+  }
+
+  if (answer === 'c' || answer === 'cancel') {
+    return 'cancel';
+  }
+
+  return 'skip';
+}
+
+async function chooseCli(rl) {
+  stdout.write('Which CLI do you want to install AI Core for?\n');
+  stdout.write('  1. Codex\n\n');
+
+  const answer = normalizeAnswer(await rl.question('Select an option [1]: '));
+
+  if (answer === '' || answer === '1' || answer === 'codex') {
+    return 'codex';
+  }
+
+  throw new Error(`Unsupported CLI selection: ${answer}`);
+}
+
+async function confirmInstall(rl, targetDir) {
+  const answer = normalizeAnswer(
+    await rl.question(`Install AI Core into ${path.join(targetDir, '.codex')}? [Y/n] `),
+  );
+
+  return answer === '' || answer === 'y' || answer === 'yes';
+}
+
+async function main() {
+  const targetDir = process.cwd();
+  const rl = createPrompter();
+
+  try {
+    if (!fs.existsSync(sourceCoreDir)) {
+      throw new Error(`Package is missing core assets: ${sourceCoreDir}`);
+    }
+
+    const selectedCli = await chooseCli(rl);
+
+    if (selectedCli !== 'codex') {
+      throw new Error(`Unsupported CLI: ${selectedCli}`);
+    }
+
+    if (!(await confirmInstall(rl, targetDir))) {
+      stdout.write('Installation cancelled.\n');
+      return;
+    }
+
+    const result = await installCodex({
+      targetDir,
+      sourceCoreDir,
+      confirm: (question) => askConflict(rl, question),
+    });
+
+    stdout.write('\nAI Core installed for Codex.\n');
+    stdout.write(`Target: ${result.targetDir}\n`);
+    stdout.write(`Copied: ${result.copied}\n`);
+    stdout.write(`Overwritten: ${result.overwritten}\n`);
+    stdout.write(`Skipped: ${result.skipped}\n`);
+  } finally {
+    rl.close();
+  }
+}
+
+function createPrompter() {
+  if (stdin.isTTY) {
+    return readline.createInterface({ input: stdin, output: stdout });
+  }
+
+  const answers = fs.readFileSync(0, 'utf8').split(/\r?\n/);
+  let index = 0;
+
+  return {
+    async question(prompt) {
+      stdout.write(prompt);
+      const answer = answers[index] || '';
+      index += 1;
+      return answer;
+    },
+    close() {},
+  };
+}
+
+main().catch((error) => {
+  console.error(`Error: ${error.message}`);
+  process.exitCode = 1;
+});

package/core/README.md

@@ -0,0 +1,162 @@
+# AI Core, Enterprise SDLC Framework
+
+> Framework source of truth for AI agents, commands, rules, templates, and workflows.
+> Compatible with Claude Code, Cursor, and Windsurf.
+
+## 🎯 Purpose
+
+AI Core turns AI coding assistants into a small structured delivery team following Agile/Scrum roles: BA, Tech Lead, Developer, QA, and Scrum Master.
+
+Important separation:
+
+- `core/` is framework-only and should be portable across projects.
+- `config/` is project-specific configuration.
+- `project/` is project-specific runtime state.
+- `docs/project/` contains product and project documentation such as requirements, specs, plans, and API docs.
+- `docs/runtime/` contains operational AI Core documentation such as ADRs, refactor plans, runbooks, QA evidence, and technical notes.
+
+## 📁 Framework structure
+
+`core/` contains reusable framework assets only:
+
+- `agents/`, role definitions
+- `commands/`, slash-command workflows
+- `rules/`, strict constraints AI must follow
+- `templates/`, reusable document templates
+- `workflows/`, lifecycle specs
+- `config/`, framework schemas only
+- `scripts/`, framework utilities
+
+`core/` MUST NOT contain project runtime state such as tickets, backlog, sprints, releases, or bugs.
+
+## 📁 Project runtime structure
+
+A project using this framework should have:
+
+- `config/project-config.yaml`, project-specific settings
+- `config/project-structure.yaml`, path conventions for this project
+- `project/backlog/backlog.json`, backlog ordering and prioritization source of truth
+- `project/tickets/TICKET-XXX.json`, ticket details and state machine history
+- `project/bugs/BUG-XXX.json`, bug state
+- `project/sprints/SPRINT-XXX.json`, sprint plans and reports
+- `project/releases/vX.Y.Z.json`, release records
+- `project/user-requests.jsonl`, append-only user request log
+- `project/views/`, generated views for humans
+- `docs/project/requirements/`, reverse-documented and stakeholder-provided requirements
+- `docs/project/specs/`, approved feature and behavior specs
+- `docs/project/user-stories/`, user story drafts and supporting product notes
+- `docs/project/plans/`, implementation plans linked from tickets
+- `docs/project/api/`, API documentation
+- `docs/runtime/refactor/`, refactor plans
+- `docs/runtime/adr/`, Architecture Decision Records
+- `docs/runtime/technical/`, technical designs
+- `docs/runtime/runbooks/`, operational runbooks
+- `docs/runtime/qa/`, QA plans and reports
+
+## 🚀 Quick Start
+
+1. Copy `core/` into your project root.
+2. Run `/setup-project` to create `config/`, `project/`, and docs scaffolding.
+3. Run `/sync-platforms` to export framework instructions to Claude Code, Cursor, and Windsurf.
+4. Start with `/detect-stack`, `/discover-codebase`, then `/analyze-requirements`.
+
+## 🧭 Guided workflow
+
+This framework is chat-first. In your AI chat window, type the workflow command directly:
+
+```text
+/analyze-requirements "User can reset password"
+/groom-ticket TICKET-001 5
+next TICKET-001
+```
+
+The AI must infer the correct agent from command metadata (`owner_agent` / `requires_agents`). Users should not need to type agent names. The executable runner exists for AI tooling and CI, not as the normal user interface.
+
+For guided mode, ask naturally:
+
+```text
+guide /groom-ticket TICKET-001 5
+```
+
+The AI should execute one step, report the completed command, ticket state before/after, updated `project` files, validation results, and the next recommended chat command. It must ask before continuing and must not auto-run steps requiring missing arguments like `<story_points>` or `<pr_url>`.
+
+## 🤖 Agents
+
+| Agent | Role | Can do | Must not do |
+|-------|------|--------|-------------|
+| `business-analyst` | BA + PM | Requirements, user stories, backlog priority | Write code, technical estimate |
+| `tech-lead` | Architect + reviewer | Design, review, ADR, security | Self-merge own PR |
+| `developer` | Engineer | Implement tasks and tests | Merge PR, approve own work |
+| `qa-tester` | QA | Test plan, bug report, fix verification | Modify production code |
+| `scrum-master` | Delivery coordinator | Sprint planning, release, metrics | Technical decisions |
+
+## ⚙️ Commands
+
+See `commands/README.md` for the full catalog.
+
+Core workflow:
+
+`/analyze-requirements` → `/groom-ticket` → `/write-plan` → `/mark-ready` → `/plan-sprint` → `/implement-task` → `/create-pr` → `/techlead-review` → `/merge-pr` → `/smoke-test`
+
+Project setup and reporting:
+
+- `/setup-project`
+- `/detect-stack`
+- `/discover-codebase`
+- `/validate-state`
+- `/sprint-report`
+- `/sync-platforms`
+
+## 📊 State Machine
+
+Tickets in `project/tickets/` move through:
+
+`DRAFT → GROOMED → READY → IN_PROGRESS → IN_REVIEW → QA → DONE`
+
+Side states:
+
+- `BLOCKED`
+- `CANCELLED`
+
+Transitions must go through commands, not manual JSON edits.
+
+## 📌 Backlog model
+
+Backlog source of truth is `project/backlog/backlog.json`.
+
+Ticket details are in `project/tickets/TICKET-XXX.json`.
+
+Generated views can be written to `project/views/`.
+
+This avoids treating the ticket folder itself as the backlog. The ticket folder stores ticket details, while the backlog file owns ranking and prioritization.
+
+## 🧱 Refactor planning
+
+Large refactors should use:
+
+- `docs/runtime/refactor/<name>-refactor-plan.md`
+- `core/templates/technical/refactor-plan-template.md`
+- `docs/runtime/adr/NNN-title.md` if the refactor changes architecture
+- `project/tickets/TICKET-XXX.json` for each executable refactor step
+
+## 🛠️ Platform Sync
+
+User-facing command:
+
+```text
+/sync-platforms
+```
+
+Internal executable used by AI tooling/CI:
+
+`bash core/scripts/sync-platforms.sh`
+
+Generated files:
+
+- `.claude/agents/`
+- `.claude/commands/`
+- `CLAUDE.md`
+- `.cursor/rules/*.mdc`
+- `.windsurfrules`
+
+Generated files are exports. Edit `core/` source files instead.

package/core/agents/README.md

@@ -0,0 +1,32 @@
+# 🎭 Agents Directory
+
+Each `.md` file defines one agent persona.
+
+## Standard Format (YAML frontmatter)
+
+```yaml
+---
+name: agent-name
+display_name: "Human Readable Name"
+role: ROLE_CODE
+version: 1.0.0
+model_preference: opus | sonnet | haiku
+can_invoke_commands: [...]
+cannot_invoke_commands: [...]
+read_access: [...]
+write_access: [...]
+escalates_to: other-agent
+---
+```
+
+## Gold standard
+
+See `business-analyst.md` for a full example.
+
+## Available agents
+
+- `business-analyst.md` - BA + PM (combined for small teams)
+- `tech-lead.md` - Tech Lead + Architect + Security
+- `developer.md` - Developer
+- `qa-tester.md` - QA
+- `scrum-master.md` - SM + DevOps