ai-core-framework 0.1.0 → 0.3.0

package/templates/project/project-structure.yaml

@@ -0,0 +1,76 @@
+# Project-specific structure map copied by /setup-project into docs/config/project-structure.yaml
+# Framework folders remain framework-only. Runtime state and project docs live outside them.
+
+state:
+  root: "docs/runtime/project"
+  tickets: "docs/runtime/project/tickets"
+  backlog: "docs/runtime/project/backlog"
+  bugs: "docs/runtime/project/bugs"
+  sprints: "docs/runtime/project/sprints"
+  releases: "docs/runtime/project/releases"
+  metrics: "docs/runtime/project/metrics"
+  views: "docs/runtime/project/views"
+  test_runs: "docs/runtime/project/test-runs"
+  incidents: "docs/runtime/project/incidents"
+  audit_log: "docs/runtime/project/audit-log.jsonl"
+
+project_docs:
+  root: "docs/project"
+  product: "docs/project/product"
+  planning: "docs/project/planning"
+  specs: "docs/project/specs"
+  user_stories: "docs/project/user-stories"
+  plans: "docs/project/plans"
+  requirements: "docs/project/requirements"
+  api: "docs/project/api"
+
+runtime_docs:
+  root: "docs/runtime"
+  refactor: "docs/runtime/refactor"
+  adr: "docs/runtime/adr"
+  technical: "docs/runtime/technical"
+  runbooks: "docs/runtime/runbooks"
+  qa: "docs/runtime/qa"
+  test_runs: "docs/runtime/test-runs"
+  verifications: "docs/runtime/verifications"
+  incidents: "docs/runtime/incidents"
+
+backlog:
+  source_of_truth: "docs/runtime/project/backlog/backlog.json"
+  ticket_details: "docs/runtime/project/tickets/TICKET-XXX.json"
+  generated_views: "docs/runtime/project/views"
+
+ticket_docs:
+  spec_path_field: "spec_path"
+  spec_dir: "docs/project/specs"
+  implementation_plan_path_field: "implementation_plan_path"
+  plan_dir: "docs/project/plans"
+
+refactor:
+  plan_dir: "docs/runtime/refactor"
+  template: "templates/technical/refactor-plan-template.md"
+  requires_ticket_breakdown: true
+  requires_adr_when_architectural: true
+
+release:
+  records: "docs/runtime/project/releases/vX.Y.Z.json"
+  schema: "docs/config/release.schema.json"
+  template: "templates/release/release-record-template.json"
+  requires_rollback_verification: true
+  requires_post_release_smoke: true
+
+scripts:
+  canonical: "scripts"
+  generated_root: "scripts"
+  command_runner: "scripts/ai-core.sh"
+  workflow_handlers: "scripts/workflow.sh"
+  audit_validator: "scripts/validate-audit-log.sh"
+  audit_log: "docs/runtime/project/audit-log.jsonl"
+
+ci:
+  governance_template: "templates/ci/ai-core-governance.yml"
+  app_templates: "templates/ci"
+
+docs_policy:
+  project_override: "docs/config/docs-policy.json"
+  default: "docs/config/docs-policy.default.json"

package/{core/templates → templates}/qa/bug-report-template.md

@@ -367,5 +367,5 @@ DO NOT EDIT BELOW - auto-populated
 -->
 
 <!-- TEMPLATE_VERSION: 1.0.0 -->
-<!-- SCHEMA: core/config/bug.schema.json -->
+<!-- SCHEMA: docs/config/bug.schema.json -->
 <!-- FILED_BY_AGENT: [agent-name] -->

package/{core/templates → templates}/requirements/user-story-template.md

@@ -378,4 +378,4 @@ DO NOT EDIT BELOW - auto-populated fields
 <!-- TEMPLATE_VERSION: 1.0.0 -->
 <!-- CREATED_BY_AGENT: business-analyst -->
 <!-- NEXT_AGENT: tech-lead -->
-<!-- SCHEMA: core/config/ticket.schema.json -->
+<!-- SCHEMA: docs/config/ticket.schema.json -->

package/{core/workflows → workflows}/bug-lifecycle.md

@@ -10,7 +10,7 @@ Make bugs reproducible, prioritized, fixed with regression coverage, and verifie
 
 1. Discovery
    - Any agent or user reports a defect with `/report-bug`.
-   - Bug is created in `project/bugs/` with status `NEW` or `NEEDS_MORE_INFO`.
+   - Bug is created in `docs/runtime/project/bugs/` with status `NEW` or `NEEDS_MORE_INFO`.
 
 2. Triage
    - BA runs `/triage-bug` with Tech Lead and QA input.
@@ -46,8 +46,8 @@ Make bugs reproducible, prioritized, fixed with regression coverage, and verifie
 
 ## 📊 Artifacts
 
-- `project/bugs/BUG-XXX.json`
-- Linked ticket in `project/tickets/`
+- `docs/runtime/project/bugs/BUG-XXX.json`
+- Linked ticket in `docs/runtime/project/tickets/`
 - Verification report
 - Regression tests
 

package/{core/workflows → workflows}/feature-lifecycle.md

@@ -82,7 +82,7 @@
 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`
+6. BA creates `docs/runtime/project/tickets/TICKET-XXX.json` with `spec_path`
 7. BA output HANDOFF → tech-lead
 
 ### Gates
@@ -181,7 +181,7 @@ Each requirement should finish in one session (< 30 minutes of BA work).
    - 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`
+3. Create `docs/runtime/project/sprints/SPRINT-XXX.json`
 
 ### Gates
 - ✅ Total points ≤ team capacity

package/{core/workflows → workflows}/sprint-lifecycle.md

@@ -46,8 +46,8 @@ Ensure sprint commitments are realistic, tracked, and closed with factual metric
 
 ## 📊 Artifacts
 
-- `project/sprints/SPRINT-XXX.json`
-- `project/metrics/`
+- `docs/runtime/project/sprints/SPRINT-XXX.json`
+- `docs/runtime/project/metrics/`
 - Retrospective notes
 - Sprint report
 

package/core/README.md

@@ -1,162 +0,0 @@
-# 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/skills/project-setup-project/SKILL.md

@@ -1,113 +0,0 @@
----
-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/templates/project/docs-policy.json

@@ -1,3 +0,0 @@
-{
-  "extends": "core/config/docs-policy.default.json"
-}

package/core/templates/project/project-structure.yaml

@@ -1,76 +0,0 @@
-# Project-specific structure map copied by /setup-project into config/project-structure.yaml
-# core remains framework-only. Runtime state and project docs live outside core.
-
-state:
-  root: "project"
-  tickets: "project/tickets"
-  backlog: "project/backlog"
-  bugs: "project/bugs"
-  sprints: "project/sprints"
-  releases: "project/releases"
-  metrics: "project/metrics"
-  views: "project/views"
-  test_runs: "project/test-runs"
-  incidents: "project/incidents"
-  audit_log: "project/audit-log.jsonl"
-
-project_docs:
-  root: "docs/project"
-  product: "docs/project/product"
-  planning: "docs/project/planning"
-  specs: "docs/project/specs"
-  user_stories: "docs/project/user-stories"
-  plans: "docs/project/plans"
-  requirements: "docs/project/requirements"
-  api: "docs/project/api"
-
-runtime_docs:
-  root: "docs/runtime"
-  refactor: "docs/runtime/refactor"
-  adr: "docs/runtime/adr"
-  technical: "docs/runtime/technical"
-  runbooks: "docs/runtime/runbooks"
-  qa: "docs/runtime/qa"
-  test_runs: "docs/runtime/test-runs"
-  verifications: "docs/runtime/verifications"
-  incidents: "docs/runtime/incidents"
-
-backlog:
-  source_of_truth: "project/backlog/backlog.json"
-  ticket_details: "project/tickets/TICKET-XXX.json"
-  generated_views: "project/views"
-
-ticket_docs:
-  spec_path_field: "spec_path"
-  spec_dir: "docs/project/specs"
-  implementation_plan_path_field: "implementation_plan_path"
-  plan_dir: "docs/project/plans"
-
-refactor:
-  plan_dir: "docs/runtime/refactor"
-  template: "core/templates/technical/refactor-plan-template.md"
-  requires_ticket_breakdown: true
-  requires_adr_when_architectural: true
-
-release:
-  records: "project/releases/vX.Y.Z.json"
-  schema: "core/config/release.schema.json"
-  template: "core/templates/release/release-record-template.json"
-  requires_rollback_verification: true
-  requires_post_release_smoke: true
-
-scripts:
-  canonical: "core/scripts"
-  generated_root: "scripts"
-  command_runner: "core/scripts/ai-core.sh"
-  workflow_handlers: "core/scripts/workflow.sh"
-  audit_validator: "core/scripts/validate-audit-log.sh"
-  audit_log: "project/audit-log.jsonl"
-
-ci:
-  governance_template: "core/templates/ci/ai-core-governance.yml"
-  app_templates: "core/templates/ci"
-
-docs_policy:
-  project_override: "config/docs-policy.json"
-  default: "core/config/docs-policy.default.json"