ai-core-framework 0.1.0

package/core/templates/ci/ai-core-governance.yml

@@ -0,0 +1,112 @@
+name: AI Core Governance
+
+on:
+  pull_request:
+    paths:
+      - "core/**"
+      - "config/**"
+      - "project/**"
+      - "docs/**"
+      - "scripts/**"
+      - ".github/workflows/ai-core-governance.yml"
+  push:
+    branches: [main, develop, "release/**"]
+    paths:
+      - "core/**"
+      - "config/**"
+      - "project/**"
+      - "docs/**"
+      - "scripts/**"
+      - ".github/workflows/ai-core-governance.yml"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  governance:
+    name: Governance Gates
+    runs-on: ubuntu-latest
+    timeout-minutes: 8
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update -qq
+          sudo apt-get install -y jq
+          npm install -g ajv-cli@5
+
+      - name: Make scripts executable
+        run: chmod +x core/scripts/*.sh
+
+      - name: Validate ticket schemas
+        run: |
+          set -e
+          for ticket in project/tickets/*.json; do
+            if [ ! -f "$ticket" ]; then continue; fi
+            ajv validate -s core/config/ticket.schema.json -d "$ticket"
+          done
+
+      - name: Validate backlog schema
+        run: |
+          if [ ! -f "project/backlog/backlog.json" ]; then
+            echo "No backlog file, skipping"
+            exit 0
+          fi
+          ajv validate -s core/config/backlog.schema.json -d project/backlog/backlog.json
+
+      - name: Validate release schemas
+        run: |
+          set -e
+          for release in project/releases/*.json; do
+            if [ ! -f "$release" ]; then continue; fi
+            ajv validate -s core/config/release.schema.json -d "$release"
+          done
+
+      - name: Validate state
+        run: bash core/scripts/validate-state.sh
+
+      - name: Validate docs
+        if: github.event_name == 'pull_request'
+        run: bash core/scripts/validate-docs.sh --base origin/${{ github.base_ref }}
+
+      - name: Validate permissions
+        run: bash core/scripts/validate-permissions.sh
+
+      - name: Validate audit log
+        run: bash core/scripts/validate-audit-log.sh
+
+      - name: Generate views smoke test
+        run: bash core/scripts/generate-views.sh
+
+      - name: Check state history immutability
+        if: github.event_name == 'pull_request'
+        run: |
+          CHANGED=$(git diff --name-only origin/${{ github.base_ref }}...HEAD -- 'project/tickets/*.json' || true)
+          if [ -z "$CHANGED" ]; then
+            echo "No ticket changes"
+            exit 0
+          fi
+
+          ERRORS=0
+          for ticket in $CHANGED; do
+            if [ ! -f "$ticket" ]; then
+              echo "::warning::Ticket deleted: $ticket"
+              continue
+            fi
+
+            BASE_HISTORY_COUNT=$(git show origin/${{ github.base_ref }}:"$ticket" 2>/dev/null | jq '.state_history | length' || echo "0")
+            HEAD_HISTORY_COUNT=$(jq '.state_history | length' "$ticket")
+
+            if [ "$HEAD_HISTORY_COUNT" -lt "$BASE_HISTORY_COUNT" ]; then
+              echo "::error file=$ticket::State history entries removed"
+              ERRORS=$((ERRORS + 1))
+            fi
+          done
+
+          if [ "$ERRORS" -gt 0 ]; then
+            exit 1
+          fi

package/core/templates/ci/node-pnpm.yml

@@ -0,0 +1,35 @@
+name: Node PNPM CI
+
+on:
+  pull_request:
+    branches: [develop, main, "release/**"]
+  push:
+    branches: [develop, main]
+
+env:
+  NODE_VERSION: "20"
+  PNPM_VERSION: "9"
+
+jobs:
+  node-ci:
+    name: Lint, Typecheck, Test
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: pnpm/action-setup@v3
+        with:
+          version: ${{ env.PNPM_VERSION }}
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run lint
+      - run: pnpm run typecheck
+      - run: pnpm run test:unit --coverage

package/core/templates/pm/retrospective-template.md

@@ -0,0 +1,47 @@
+# Retrospective Template
+
+## Sprint
+
+- Sprint ID:
+- Date:
+- Facilitator:
+- Attendees:
+
+## Metrics Snapshot
+
+- Committed points:
+- Completed points:
+- Carryover points:
+- Escaped defects:
+- Average cycle time:
+- Blocked ticket count:
+
+## What Went Well
+
+- 
+
+## What Did Not Go Well
+
+- 
+
+## Root Causes
+
+| Issue | Root cause | Evidence |
+|-------|------------|----------|
+| | | |
+
+## Action Items
+
+| Action | Owner | Due date | Success signal |
+|--------|-------|----------|----------------|
+| | | | |
+
+## Process Rule Changes
+
+- Rule or workflow to update:
+- Reason:
+- Owner:
+
+## Follow-up Tickets
+
+- 

package/core/templates/pm/sprint-plan-template.md

@@ -0,0 +1,45 @@
+# Sprint Plan Template
+
+## Sprint Metadata
+
+- Sprint ID:
+- Sprint name:
+- Start date:
+- End date:
+- Scrum Master:
+- Sprint goal:
+
+## Capacity
+
+| Role | Available days | Notes |
+|------|----------------|-------|
+| Developer | | |
+| Tech Lead | | |
+| QA | | |
+
+- Configured capacity points:
+- Reserved bug/support capacity:
+- Committed feature capacity:
+
+## Committed Tickets
+
+| Ticket | Title | Points | Owner | Dependencies | Risk |
+|--------|-------|--------|-------|--------------|------|
+| | | | | | |
+
+## Sprint Risks
+
+| Risk | Probability | Impact | Mitigation | Owner |
+|------|-------------|--------|------------|-------|
+| | | | | |
+
+## Out of Scope
+
+- 
+
+## Approval
+
+- Scrum Master:
+- Tech Lead:
+- BA/PM:
+- QA:

package/core/templates/pr/pull-request-template.md

@@ -0,0 +1,247 @@
+<!--
+Pull Request Template
+Instructions for developer:
+- Fill all required sections (marked with *)
+- Delete sections not applicable
+- Keep it concise but informative
+- Reviewer will use this as their guide
+-->
+
+## 📝 Summary *
+
+<!-- 1-3 sentences: what does this PR do and why? -->
+
+**Ticket**: [TICKET-XXX](./project/tickets/TICKET-XXX.json) <!-- Auto-filled by /create-pr -->
+
+**Type**: <!-- feature | bugfix | hotfix | refactor | chore | docs -->
+
+---
+
+## 🎯 What changed *
+
+<!-- Bullet list of the main changes -->
+
+- 
+- 
+- 
+
+---
+
+## 🧪 How to test *
+
+<!-- Reviewer should be able to manually verify with these steps -->
+
+### Acceptance Criteria Coverage
+
+<!-- List each AC scenario and how it's tested -->
+
+- [ ] **Scenario 1**: [Happy path description]
+  - Test: `tests/path/to/test.spec.ts:lineNumber`
+  - Manual: `[steps to reproduce]`
+
+- [ ] **Scenario 2**: [Edge case description]
+  - Test: `tests/path/to/test.spec.ts:lineNumber`
+  - Manual: `[steps]`
+
+- [ ] **Scenario 3**: [Error case description]
+  - Test: `tests/path/to/test.spec.ts:lineNumber`
+
+### Additional testing
+
+<!-- Anything beyond AC that reviewer should check -->
+
+- 
+
+---
+
+## 📸 Screenshots / Recordings
+
+<!-- REQUIRED if UI changes. Delete section otherwise. -->
+
+### Before
+<!-- [screenshot or "N/A - new feature"] -->
+
+### After
+<!-- [screenshot] -->
+
+### Mobile (if applicable)
+<!-- [screenshot] -->
+
+---
+
+## 🔧 Technical Notes
+
+<!-- Reviewer's mental model - what did you decide and why -->
+
+### Approach
+
+<!-- 2-3 sentences about technical approach -->
+
+### Key decisions
+
+- **Decision 1**: [what] - [why]
+- **Decision 2**: [what] - [why]
+
+### Trade-offs considered
+
+<!-- What alternatives did you consider? Why didn't you choose them? -->
+
+- 
+
+### Follow-up work
+
+<!-- Not blocking this PR, but related work -->
+
+- [ ] TICKET-YYY: [description]
+
+---
+
+## 📋 Self-Review Checklist *
+
+<!-- Developer: check each item before requesting review -->
+
+### Functionality
+- [ ] All acceptance criteria scenarios implemented
+- [ ] Manual testing completed on local/staging
+- [ ] No regressions in related features (spot-checked)
+
+### Code Quality
+- [ ] Code follows project style guide
+- [ ] Names are descriptive (no `x`, `tmp`, `data`)
+- [ ] Functions < 50 lines, files < 500 lines
+- [ ] No commented-out code
+- [ ] No `console.log` / `print` debug statements
+- [ ] No TODO/FIXME without linked ticket
+
+### Testing
+- [ ] Unit tests for new logic
+- [ ] Integration tests for API/DB changes
+- [ ] Edge cases covered (null, empty, boundary, error)
+- [ ] Diff coverage ≥ 80%
+- [ ] No disabled/skipped tests (or justified with ticket)
+- [ ] All tests pass locally
+
+### Security
+- [ ] No secrets committed (keys, passwords, tokens)
+- [ ] Input validation on all user inputs
+- [ ] Authorization checks (if applicable)
+- [ ] Output encoding (if rendering user content)
+- [ ] SQL/NoSQL queries parameterized
+- [ ] No new dependencies with known vulnerabilities
+
+### Documentation
+- [ ] API docs updated (if endpoint changed)
+- [ ] README updated (if setup changed)
+- [ ] CHANGELOG entry added
+- [ ] ADR created (if architecture decision)
+- [ ] Complex logic has explaining comments
+
+### Git Hygiene
+- [ ] Branch name follows convention (`type/TICKET-XXX-slug`)
+- [ ] Commits follow Conventional Commits format
+- [ ] Atomic commits (one logical change each)
+- [ ] TDD pattern visible (test commits before feature commits)
+- [ ] No "WIP" or debug commits
+- [ ] Branch up-to-date with develop
+
+---
+
+## 🚨 Breaking Changes
+
+<!-- Any? Describe migration path. Delete section if none. -->
+
+- [ ] This PR contains breaking changes
+
+### What breaks
+- 
+
+### Migration path
+- 
+
+### Affected consumers
+- 
+
+---
+
+## 🔗 Related
+
+<!-- Links to relevant context -->
+
+- **ADR**: [ADR-XXXX](./docs/runtime/adr/XXXX-title.md) <!-- if applicable -->
+- **Design**: [Figma link] <!-- if applicable -->
+- **Spec**: [Doc link] <!-- if applicable -->
+- **Previous PRs**: #XXX, #YYY <!-- related/dependency -->
+- **Follow-up PRs**: (planned) <!-- if applicable -->
+
+---
+
+## 📊 Impact Assessment
+
+### Performance
+<!-- Expected impact on performance. Benchmarks if significant. -->
+
+- [ ] No performance regression expected
+- [ ] Performance improvement: [details]
+- [ ] Performance impact acceptable: [details + justification]
+
+### Database
+<!-- Migration? Schema change? Indexes? -->
+
+- [ ] No database changes
+- [ ] Migration included: `migrations/YYYYMMDD_description.sql`
+- [ ] Backward compatible migration
+- [ ] Requires maintenance window
+
+### Deployment
+<!-- Any special considerations? -->
+
+- [ ] Standard deployment (no special steps)
+- [ ] Requires env variable: `NEW_VAR_NAME` (documented in `.env.example`)
+- [ ] Requires infra change (see: [ticket/doc])
+- [ ] Feature flag: `flag_name` (default: off)
+- [ ] Rollback plan: [describe]
+
+---
+
+## ✅ Reviewer Instructions
+
+### Suggested review order
+1. Read this description (you're doing it ✓)
+2. Review [TICKET-XXX acceptance criteria](./ticket-link)
+3. Look at [files changed](./files-link)
+4. Run tests locally (optional)
+5. Test manually: [specific scenario]
+
+### Particularly important to review
+<!-- Point reviewer to areas needing extra attention -->
+
+- 
+
+### Questions for reviewer
+<!-- Anything you're uncertain about -->
+
+- 
+
+---
+
+## 📦 Metadata (auto-populated by /create-pr)
+
+<!-- Don't edit these - /create-pr fills them -->
+
+- **Branch**: `<branch_name>`
+- **Base**: `develop`
+- **Commits**: `<count>`
+- **Lines**: `+<added> / -<removed>`
+- **Files changed**: `<count>`
+- **Coverage**: diff `<pct>%` / overall `<pct>%`
+- **CI status**: <!-- check GitHub -->
+
+---
+
+<!-- 
+DO NOT EDIT BELOW THIS LINE - auto-generated by /create-pr
+-->
+
+<!-- TICKET_REF: TICKET-XXX -->
+<!-- AGENT: developer -->
+<!-- TEMPLATE_VERSION: 1.0.0 -->

package/core/templates/project/CODEOWNERS

@@ -0,0 +1,11 @@
+# AI Core governance ownership.
+#
+# Replace placeholder teams/users for each consuming repo.
+/core/ @tech-leads
+/config/ @scrum-masters @tech-leads
+/project/ @scrum-masters @tech-leads
+/docs/runtime/adr/ @tech-leads
+/docs/project/specs/ @product-owners @tech-leads
+/docs/project/plans/ @tech-leads
+/docs/runtime/runbooks/ @tech-leads @qa-leads
+/.github/workflows/ @tech-leads

package/core/templates/project/docs-policy.json

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

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

@@ -0,0 +1,137 @@
+# ====================================================================
+# PROJECT CONFIGURATION
+# Single source of truth for project settings.
+# Every agent and command reads from here.
+# ====================================================================
+
+project:
+  name: "My Awesome Project"
+  description: ""
+  repo_url: ""
+  team_size: "small"  # solo | small | medium | enterprise
+
+# --- Tech stack (auto-detect or manual set) ---
+stack:
+  language: "typescript"          # typescript | python | java | go | ...
+  runtime: "node"                 # node | deno | bun | python | jvm | ...
+  framework: "nextjs"             # nextjs | express | django | spring | ...
+  database: "postgres"
+  test_runner: "vitest"           # vitest | jest | pytest | junit | ...
+  package_manager: "pnpm"         # npm | yarn | pnpm | pip | poetry | ...
+
+# --- Git workflow ---
+git:
+  main_branch: "main"
+  develop_branch: "develop"
+  protected_branches:
+    - "main"
+    - "develop"
+    - "release/*"
+    - "staging"
+  branch_prefix:
+    feature: "feature/"
+    bugfix: "bugfix/"
+    hotfix: "hotfix/"
+    chore: "chore/"
+    refactor: "refactor/"
+  commit_convention: "conventional"  # conventional | gitmoji | custom
+  allowed_commit_types:
+    - feat
+    - fix
+    - docs
+    - style
+    - refactor
+    - perf
+    - test
+    - chore
+    - build
+    - ci
+    - revert
+
+# --- Quality gates ---
+quality:
+  coverage_threshold:
+    diff: 80      # % coverage on new code in PR
+    overall: 70   # % total coverage
+  lint:
+    blocking: true   # Lint errors block merge
+    warnings_allowed: true
+  max_complexity: 10        # Cyclomatic complexity per function
+  max_file_lines: 500
+  max_function_lines: 50
+
+# --- Scrum configuration ---
+scrum:
+  sprint_length_days: 14
+  sprint_capacity_points: 30   # Total story points per sprint for team 2-5
+  velocity_tracking: true
+  ceremonies:
+    planning: true
+    daily_standup: true
+    review: true
+    retrospective: true
+  story_point_scale: "fibonacci"  # fibonacci | tshirt | linear
+  fibonacci_values: [1, 2, 3, 5, 8, 13, 21]
+
+# --- Ticket states ---
+ticket_states:
+  - DRAFT          # Just created, needs grooming
+  - GROOMED        # BA + Tech Lead reviewed
+  - READY          # Passed DoR, ready for sprint
+  - IN_PROGRESS    # Being worked on
+  - IN_REVIEW      # PR created, awaiting review
+  - QA             # Merged, being tested
+  - DONE           # Passed QA
+  - BLOCKED        # Blocked (can be from any state)
+  - CANCELLED      # Won't do
+
+# --- Agents registry ---
+agents:
+  business-analyst:
+    enabled: true
+    model: opus
+    max_tokens_per_session: 100000
+  tech-lead:
+    enabled: true
+    model: opus
+    max_tokens_per_session: 150000
+  developer:
+    enabled: true
+    model: sonnet
+    max_tokens_per_session: 200000
+  qa-tester:
+    enabled: true
+    model: sonnet
+    max_tokens_per_session: 100000
+  scrum-master:
+    enabled: true
+    model: sonnet
+    max_tokens_per_session: 80000
+
+# --- Platform sync ---
+platforms:
+  claude_code:
+    enabled: true
+    output_dir: ".claude"
+  cursor:
+    enabled: true
+    output_dir: ".cursor/rules"
+    format: "mdc"
+  windsurf:
+    enabled: true
+    output_file: ".windsurfrules"
+
+# --- Notifications (optional integrations) ---
+notifications:
+  slack_webhook: ""
+  github_issues: true
+  email: ""
+
+# --- Feature flags ---
+features:
+  auto_create_adr: true          # Automatically create ADR when there is an architecture decision
+  enforce_tdd: true              # Block code without test first
+  require_pr_template: true
+  require_handoff_protocol: true
+  metric_tracking: true
+  ai_suggested_reviewers: true