ai-core-framework 0.1.0

package/core/scripts/workflow.sh

@@ -0,0 +1,513 @@
+#!/usr/bin/env bash
+# core/scripts/workflow.sh
+#
+# Executable handlers for AI Core state workflow commands.
+
+set -euo pipefail
+
+COMMAND="${1:-}"
+shift || true
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+log_info() { echo -e "${BLUE}i${NC}  $1"; }
+log_pass() { echo -e "${GREEN}+${NC}  $1"; }
+log_fail() { echo -e "${RED}x${NC}  $1"; }
+
+require_jq() {
+  if ! command -v jq >/dev/null 2>&1; then
+    log_fail "jq not installed. Install with: brew install jq"
+    exit 2
+  fi
+}
+
+now_utc() {
+  date -u +%Y-%m-%dT%H:%M:%SZ
+}
+
+agent_name() {
+  local agent="${AI_AGENT:-unknown-agent}"
+  if [[ "$agent" == *-agent ]]; then
+    printf '%s' "$agent"
+  else
+    printf '%s-agent' "$agent"
+  fi
+}
+
+ticket_file() {
+  printf 'project/tickets/%s.json' "$1"
+}
+
+slugify() {
+  printf '%s' "$1" |
+    tr '[:upper:]' '[:lower:]' |
+    sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//; s/-+/-/g' |
+    cut -c1-60
+}
+
+next_ticket_id() {
+  local max_id
+  max_id=$(find project/tickets -name 'TICKET-*.json' -type f 2>/dev/null |
+    sed -E 's/.*TICKET-([0-9]+)\.json/\1/' |
+    sort -n |
+    tail -1)
+  if [ -z "$max_id" ]; then
+    printf 'TICKET-001'
+  else
+    printf 'TICKET-%03d' "$((10#$max_id + 1))"
+  fi
+}
+
+write_json() {
+  local file="$1"
+  local tmp
+  tmp=$(mktemp)
+  cat > "$tmp"
+  mv "$tmp" "$file"
+}
+
+hash_value() {
+  local value="$1"
+  if command -v sha256sum >/dev/null 2>&1; then
+    printf '%s' "$value" | sha256sum | awk '{print $1}'
+  else
+    printf '%s' "$value" | shasum -a 256 | awk '{print $1}'
+  fi
+}
+
+last_audit_hash() {
+  local audit_file="project/audit-log.jsonl"
+  if [ ! -s "$audit_file" ]; then
+    printf ''
+    return 0
+  fi
+  tail -1 "$audit_file" | jq -r '.hash // empty'
+}
+
+append_audit() {
+  local command="$1"
+  local ticket_id="$2"
+  local from_state="$3"
+  local to_state="$4"
+  local reason="$5"
+
+  mkdir -p project
+  local audit_file="project/audit-log.jsonl"
+  local at by prev payload hash
+  at=$(now_utc)
+  by=$(agent_name)
+  prev=$(last_audit_hash)
+  payload=$(jq -cn \
+    --arg at "$at" \
+    --arg by "$by" \
+    --arg command "$command" \
+    --arg ticket_id "$ticket_id" \
+    --arg from_state "$from_state" \
+    --arg to_state "$to_state" \
+    --arg reason "$reason" \
+    --arg prev_hash "$prev" \
+    '{at:$at, by_agent:$by, command:$command, ticket_id:$ticket_id, from_state:$from_state, to_state:$to_state, reason:$reason, prev_hash:$prev_hash}')
+  hash=$(hash_value "$payload")
+  jq -cn --argjson payload "$payload" --arg hash "$hash" '$payload + {hash:$hash}' >> "$audit_file"
+}
+
+transition_ticket() {
+  local ticket_id="$1"
+  local from_state="$2"
+  local to_state="$3"
+  local command="$4"
+  local reason="$5"
+  local file
+  file=$(ticket_file "$ticket_id")
+
+  if [ ! -f "$file" ]; then
+    log_fail "Ticket not found: $ticket_id"
+    exit 1
+  fi
+
+  local status
+  status=$(jq -r '.status' "$file")
+  if [ "$status" != "$from_state" ]; then
+    log_fail "$ticket_id status must be $from_state, got $status"
+    exit 1
+  fi
+
+  local at by
+  at=$(now_utc)
+  by=$(agent_name)
+
+  jq \
+    --arg status "$to_state" \
+    --arg at "$at" \
+    --arg by "$by" \
+    --arg command "$command" \
+    --arg from_state "$from_state" \
+    --arg to_state "$to_state" \
+    --arg reason "$reason" \
+    '.status = $status
+     | .updated_at = $at
+     | .state_history += [{
+         from_state: $from_state,
+         to_state: $to_state,
+         at: $at,
+         by_agent: $by,
+         by_command: $command,
+         reason: $reason
+       }]' "$file" | write_json "$file"
+
+  append_audit "$command" "$ticket_id" "$from_state" "$to_state" "$reason"
+  bash core/scripts/validate-state.sh "$ticket_id"
+  bash core/scripts/validate-permissions.sh
+  log_pass "$ticket_id transitioned $from_state -> $to_state"
+}
+
+require_ticket_field() {
+  local ticket_id="$1"
+  local query="$2"
+  local message="$3"
+  if ! jq -e "$query" "$(ticket_file "$ticket_id")" >/dev/null 2>&1; then
+    log_fail "$ticket_id: $message"
+    exit 1
+  fi
+}
+
+cmd_analyze_requirements() {
+  local requirement="${*:-}"
+  if [ ${#requirement} -lt 10 ]; then
+    log_fail "Requirement text must be at least 10 characters"
+    exit 1
+  fi
+
+  mkdir -p project/tickets docs/project/specs
+  local ticket_id file at by slug spec_path
+  ticket_id=$(next_ticket_id)
+  file=$(ticket_file "$ticket_id")
+  at=$(now_utc)
+  by=$(agent_name)
+  slug=$(slugify "$requirement")
+  [ -n "$slug" ] || slug="requirement"
+  spec_path="docs/project/specs/${ticket_id}-${slug}.md"
+
+  cat > "$spec_path" <<EOF
+# ${ticket_id}: ${requirement:0:120}
+
+## Goal
+
+${requirement}
+
+## Background
+
+Created by /analyze-requirements from stakeholder input.
+
+## Users And Stakeholders
+
+- Primary user: stakeholder
+- Owner agent: $by
+
+## In Scope
+
+- Convert the requirement into a groomable ticket.
+- Validate expected behavior through acceptance criteria.
+
+## Out Of Scope
+
+- Technical implementation details.
+- Story point estimation.
+
+## Acceptance Criteria
+
+1. Happy path: valid preconditions produce the expected outcome.
+2. Edge case: boundary input or uncommon state is handled predictably.
+3. Error case: invalid input or unavailable dependency produces a safe error and no data corruption.
+
+## Risks And Assumptions
+
+- Requirement may need refinement during grooming.
+- Technical risks are owned by /groom-ticket and /write-plan.
+
+## Next Command
+
+\`/groom-ticket ${ticket_id} <story_points>\`
+EOF
+
+  jq -n \
+    --arg id "$ticket_id" \
+    --arg title "${requirement:0:120}" \
+    --arg req "$requirement" \
+    --arg at "$at" \
+    --arg by "$by" \
+    --arg spec_path "$spec_path" \
+    '{
+      id: $id,
+      title: $title,
+      type: "feature",
+      status: "DRAFT",
+      priority: "SHOULD",
+      user_story: {
+        as_a: "stakeholder",
+        i_want: $req,
+        so_that: "business value can be validated"
+      },
+      acceptance_criteria: [
+        {scenario:"Happy path", given:"valid preconditions", when:"the user performs the requested action", then:"the expected outcome is achieved"},
+        {scenario:"Edge case", given:"boundary input or uncommon state", when:"the action is attempted", then:"the system handles it predictably"},
+        {scenario:"Error case", given:"invalid input or unavailable dependency", when:"the action is attempted", then:"the user receives a safe error and no data is corrupted"}
+      ],
+      created_at: $at,
+      created_by: $by,
+      updated_at: $at,
+      spec_path: $spec_path,
+      state_history: [{
+        from_state: null,
+        to_state: "DRAFT",
+        at: $at,
+        by_agent: $by,
+        by_command: "/analyze-requirements",
+        reason: "Created from executable requirement intake"
+      }],
+      comments: [{
+        author: $by,
+        at: $at,
+        text: ("Source requirement: " + $req)
+      }],
+      labels: ["needs-grooming"]
+    }' > "$file"
+
+  append_audit "/analyze-requirements" "$ticket_id" "null" "DRAFT" "Created from executable requirement intake"
+  bash core/scripts/validate-state.sh "$ticket_id"
+  log_pass "Created $ticket_id"
+  log_pass "Created $spec_path"
+}
+
+cmd_groom_ticket() {
+  local ticket_id="${1:-}"
+  local points="${2:-}"
+  [ -n "$ticket_id" ] || { log_fail "Usage: /groom-ticket TICKET-XXX [points]"; exit 2; }
+
+  if [ -n "$points" ]; then
+    local file at by
+    file=$(ticket_file "$ticket_id")
+    at=$(now_utc)
+    by=$(agent_name)
+    jq --argjson points "$points" --arg by "$by" --arg at "$at" \
+      '.estimate = {story_points:$points, estimated_by:$by, estimated_at:$at}
+       | .technical_approach = (.technical_approach // "Executable grooming recorded. Add detailed approach before implementation.")
+       | .risks = (.risks // [{description:"Implementation risk requires Tech Lead review", probability:"MEDIUM", impact:"MEDIUM", mitigation:"Review before sprint planning"}])' "$file" | write_json "$file"
+  fi
+
+  require_ticket_field "$ticket_id" '.user_story' "missing user_story"
+  require_ticket_field "$ticket_id" '.acceptance_criteria | length >= 3' "requires at least 3 acceptance criteria"
+  require_ticket_field "$ticket_id" '.estimate.story_points' "missing estimate.story_points; pass points or add estimate"
+  transition_ticket "$ticket_id" "DRAFT" "GROOMED" "/groom-ticket" "Executable grooming gate passed"
+}
+
+cmd_mark_ready() {
+  local ticket_id="${1:-}"
+  [ -n "$ticket_id" ] || { log_fail "Usage: /mark-ready TICKET-XXX"; exit 2; }
+  require_ticket_field "$ticket_id" '.estimate.story_points' "missing estimate"
+  require_ticket_field "$ticket_id" '.acceptance_criteria | length >= 3' "requires at least 3 acceptance criteria"
+  transition_ticket "$ticket_id" "GROOMED" "READY" "/mark-ready" "Definition of Ready gate passed"
+}
+
+cmd_write_plan() {
+  local ticket_id="${1:-}"
+  [ -n "$ticket_id" ] || { log_fail "Usage: /write-plan TICKET-XXX"; exit 2; }
+
+  local file status title slug plan_path spec_path at by
+  file=$(ticket_file "$ticket_id")
+  [ -f "$file" ] || { log_fail "Ticket not found: $ticket_id"; exit 1; }
+  status=$(jq -r '.status // empty' "$file")
+  case "$status" in
+    GROOMED|READY) ;;
+    *) log_fail "$ticket_id status must be GROOMED or READY before /write-plan, got $status"; exit 1 ;;
+  esac
+
+  mkdir -p docs/project/plans
+  title=$(jq -r '.title // .id' "$file")
+  slug=$(slugify "$title")
+  [ -n "$slug" ] || slug="implementation"
+  plan_path="docs/project/plans/${ticket_id}-${slug}-plan.md"
+  spec_path=$(jq -r '.spec_path // empty' "$file")
+  at=$(now_utc)
+  by=$(agent_name)
+
+  cat > "$plan_path" <<EOF
+# ${ticket_id}: ${title} Implementation Plan
+
+**Ticket:** \`${ticket_id}\`
+**Status at planning:** \`${status}\`
+**Spec:** ${spec_path:-Not linked}
+**Created by:** ${by}
+**Created at:** ${at}
+
+## Goal
+
+Implement the ticket scope while preserving the approved acceptance criteria and documentation obligations.
+
+## Current Context
+
+- Read \`project/tickets/${ticket_id}.json\`.
+- Read the linked spec if present.
+- Inspect affected code before editing.
+
+## Affected Files
+
+- To be confirmed by the developer before implementation.
+- Add exact paths here if codebase discovery identifies them.
+
+## Tasks
+
+- [ ] Confirm ticket scope and acceptance criteria.
+- [ ] Identify exact production files and test files.
+- [ ] Write or update failing tests for the happy path.
+- [ ] Write or update failing tests for edge/error cases.
+- [ ] Implement the smallest code change that satisfies the tests.
+- [ ] Run targeted tests and record output.
+- [ ] Update docs required by the ticket metadata.
+- [ ] Run validation gates: state, permissions, docs, audit log.
+
+## Test Strategy
+
+- Unit tests for deterministic logic.
+- Integration tests for changed boundaries.
+- Manual or smoke-test evidence before DONE.
+
+## Documentation Updates
+
+- Update \`documentation.paths\` in the ticket when docs are required.
+- Add ADR or runbook links if architecture, migration, or operations behavior changes.
+
+## Verification Commands
+
+\`\`\`text
+/validate-state
+/validate-permissions
+/validate-docs
+\`\`\`
+
+## Rollback Notes
+
+Rollback should revert the implementation commit or disable the changed behavior behind the safest available control. Add a more specific rollback path before release if this touches data, auth, billing, deployment, or migrations.
+
+## Next Command
+
+\`/implement-task ${ticket_id}\`
+EOF
+
+  jq --arg path "$plan_path" --arg at "$at" --arg by "$by" \
+    '.implementation_plan_path = $path
+     | .updated_at = $at
+     | .comments = ((.comments // []) + [{
+         author: $by,
+         at: $at,
+         text: ("Implementation plan created: " + $path)
+       }])' "$file" | write_json "$file"
+
+  append_audit "/write-plan" "$ticket_id" "$status" "$status" "Implementation plan created"
+  bash core/scripts/validate-state.sh "$ticket_id"
+  bash core/scripts/validate-permissions.sh
+  log_pass "Created $plan_path"
+  log_pass "Linked plan from $file"
+}
+
+cmd_implement_task() {
+  local ticket_id="${1:-}"
+  [ -n "$ticket_id" ] || { log_fail "Usage: /implement-task TICKET-XXX"; exit 2; }
+  if ! jq -e '.implementation_plan_path // empty' "$(ticket_file "$ticket_id")" >/dev/null 2>&1; then
+    log_info "$ticket_id has no implementation_plan_path. Recommended first: /write-plan $ticket_id"
+  fi
+  transition_ticket "$ticket_id" "READY" "IN_PROGRESS" "/implement-task" "Implementation started"
+}
+
+cmd_create_pr() {
+  local ticket_id="${1:-}"
+  local pr_url="${2:-}"
+  [ -n "$ticket_id" ] || { log_fail "Usage: /create-pr TICKET-XXX [pr_url]"; exit 2; }
+  if [ "$(jq -r '.status' "$(ticket_file "$ticket_id")")" != "IN_PROGRESS" ]; then
+    log_fail "$ticket_id status must be IN_PROGRESS before PR metadata is written"
+    exit 1
+  fi
+  if [ -n "$pr_url" ]; then
+    jq --arg pr_url "$pr_url" '.pr_url = $pr_url' "$(ticket_file "$ticket_id")" | write_json "$(ticket_file "$ticket_id")"
+  fi
+  require_ticket_field "$ticket_id" '.pr_url // empty' "missing pr_url; pass PR URL"
+  transition_ticket "$ticket_id" "IN_PROGRESS" "IN_REVIEW" "/create-pr" "PR created and linked"
+}
+
+cmd_merge_pr() {
+  local ticket_id="${1:-}"
+  [ -n "$ticket_id" ] || { log_fail "Usage: /merge-pr TICKET-XXX"; exit 2; }
+  require_ticket_field "$ticket_id" '.pr_url // empty' "missing pr_url"
+  transition_ticket "$ticket_id" "IN_REVIEW" "QA" "/merge-pr" "PR merged and ready for QA"
+}
+
+cmd_smoke_test() {
+  local ticket_id="${1:-}"
+  local evidence_path="${2:-}"
+  [ -n "$ticket_id" ] || { log_fail "Usage: /smoke-test TICKET-XXX [evidence_path]"; exit 2; }
+  if [ "$(jq -r '.status' "$(ticket_file "$ticket_id")")" != "QA" ]; then
+    log_fail "$ticket_id status must be QA before QA evidence is written"
+    exit 1
+  fi
+  [ -n "$evidence_path" ] || evidence_path="project/test-runs/${ticket_id}-$(date -u +%Y%m%d%H%M%S).md"
+  mkdir -p "$(dirname "$evidence_path")"
+  if [ ! -f "$evidence_path" ]; then
+    printf '# Smoke Test Evidence: %s\n\nGenerated by executable smoke-test gate at %s.\n' "$ticket_id" "$(now_utc)" > "$evidence_path"
+  fi
+  local at by
+  at=$(now_utc)
+  by=$(agent_name)
+  jq --arg path "$evidence_path" --arg by "$by" --arg at "$at" \
+    '.qa_evidence = {required:true, path:$path, verified_by:$by, verified_at:$at}
+     | .dod_checklist = ((.dod_checklist // {}) + {
+         code_complete:true,
+         tests_passed:true,
+         docs_updated:true,
+         review_approved:true,
+         qa_verified:true,
+         release_notes_updated:true,
+         security_checked:true
+       })
+     | .completed_at = $at' "$(ticket_file "$ticket_id")" | write_json "$(ticket_file "$ticket_id")"
+  transition_ticket "$ticket_id" "QA" "DONE" "/smoke-test" "Smoke test passed with evidence"
+}
+
+cmd_release() {
+  local version="${1:-}"
+  [ -n "$version" ] || { log_fail "Usage: /release vMAJOR.MINOR.PATCH"; exit 2; }
+  mkdir -p project/releases
+  local file="project/releases/${version}.json"
+  if [ -f "$file" ]; then
+    log_fail "Release record already exists: $file"
+    exit 1
+  fi
+  local at by
+  at=$(now_utc)
+  by=$(agent_name)
+  jq --arg version "$version" --arg at "$at" --arg by "$by" \
+    '.version = $version
+     | .created_at = $at
+     | .created_by = $by' core/templates/release/release-record-template.json > "$file"
+  log_pass "Created release record $file"
+}
+
+main() {
+  require_jq
+  case "$COMMAND" in
+    analyze-requirements) cmd_analyze_requirements "$@" ;;
+    groom-ticket) cmd_groom_ticket "$@" ;;
+    write-plan) cmd_write_plan "$@" ;;
+    mark-ready) cmd_mark_ready "$@" ;;
+    implement-task) cmd_implement_task "$@" ;;
+    create-pr) cmd_create_pr "$@" ;;
+    merge-pr) cmd_merge_pr "$@" ;;
+    smoke-test) cmd_smoke_test "$@" ;;
+    release) cmd_release "$@" ;;
+    *) log_fail "No workflow handler for $COMMAND"; exit 2 ;;
+  esac
+}
+
+main "$@"

package/core/skills/README.md

@@ -0,0 +1,21 @@
+# AI Core Skills
+
+Skills define chat-first agent behavior. Commands define workflow actions. Scripts implement deterministic checks and state updates.
+
+Use skills when the user intent is broader than one command:
+
+- `using-ai-core`: session bootstrap and command interpretation
+- `ai-core-commands`: interpret AI Core slash-command text in Codex chat
+- `brainstorming`: requirement discovery before ticket work
+- `writing-implementation-plan`: detailed plan creation before coding
+- `executing-ticket`: implementation discipline for active tickets
+- `verification-before-done`: evidence gate before completion claims
+
+Normal user interaction should stay in chat:
+
+```text
+/analyze-requirements "User can reset password"
+/groom-ticket TICKET-001 5
+/write-plan TICKET-001
+next TICKET-001
+```

package/core/skills/ai-core-commands/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: ai-core-commands
+description: Interpret AI Core slash-command text in Codex. Use when the user types AI Core commands such as /setup-project, /analyze-requirements, /document-existing-requirements, /groom-ticket, /write-plan, /implement-task, /request-log, or asks to run an AI Core workflow command.
+---
+
+# AI Core Commands
+
+Codex plugins do not expose `core/commands/*.md` as native slash-command autocomplete. This skill makes AI Core command text executable through normal chat.
+
+## Mandatory Trigger
+
+Use this skill when the user message starts with, mentions, or asks to run any AI Core command:
+
+```text
+/setup-project
+/analyze-requirements
+/document-existing-requirements
+/groom-ticket
+/mark-ready
+/write-plan
+/implement-task
+/create-pr
+/techlead-review
+/merge-pr
+/smoke-test
+/verify-fix
+/release
+/request-log
+guide /...
+next TICKET-XXX
+```
+
+## Required Behavior
+
+1. Log the user request first:
+   ```bash
+   AI_AGENT=codex bash core/scripts/log-user-request.sh "<user request text>"
+   ```
+
+2. Resolve command metadata:
+   - Search `core/commands/**/<command-name>.md`.
+   - Read the command file.
+   - Infer `owner_agent`, `requires_agents`, args, preconditions, postconditions, hard rules, and output format.
+
+3. Load the matching agent file when present:
+   - `core/agents/<owner_agent>.md`
+
+4. Execute the command in chat-first mode:
+   - Use deterministic scripts only when the command file or workflow requires them.
+   - Do not ask the user to run shell wrappers during normal use.
+   - Preserve all hard rules from `core/rules/00-global-rules.md`.
+
+5. Report:
+   - Command executed
+   - Inferred agent
+   - Files created or changed
+   - Validation result
+   - Suggested next AI Core command
+
+## Command Discovery
+
+Command files are stored under:
+
+```text
+core/commands/
+```
+
+The command name maps to a Markdown file by removing the leading slash:
+
+```text
+/analyze-requirements -> core/commands/**/analyze-requirements.md
+/request-log -> core/commands/**/request-log.md
+```
+
+If multiple files match the same command name, stop and ask for clarification.
+
+If no file matches, say the command is not defined and suggest `/request-log`, `/setup-project`, or checking `core/commands/README.md`.
+
+## Strict Rules
+
+- MUST NOT invent command behavior not present in command files.
+- MUST NOT skip required preconditions.
+- MUST NOT silently skip request logging.
+- MUST NOT modify production code unless AI Core ticket rules allow it.
+- MUST distinguish native Codex slash commands from AI Core chat commands. AI Core commands may not appear in `/` autocomplete, but they still MUST be interpreted when typed in chat.
+

package/core/skills/brainstorming/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: brainstorming
+description: Use before creating or changing product behavior. Converts a rough idea into an approved spec before ticket grooming or implementation.
+---
+
+# Brainstorming
+
+Use this before implementation work, feature creation, behavior changes, or large refactors.
+
+## Process
+
+1. Inspect current project context briefly.
+2. Ask clarifying questions one at a time when the requirement is ambiguous.
+3. Propose 2-3 approaches with tradeoffs and a recommendation.
+4. Present a concise design for user approval.
+5. Save the approved spec to `docs/project/specs/TICKET-XXX-<slug>.md`.
+6. Link the spec from `project/tickets/TICKET-XXX.json` as `spec_path`.
+7. Suggest `/groom-ticket TICKET-XXX`.
+
+## Hard Gates
+
+- Do not write production code during brainstorming.
+- Do not invent missing business requirements silently.
+- Do not estimate story points. Estimation belongs to `/groom-ticket`.
+- Do not create implementation plans here. Use `/write-plan` after the ticket is groomed or ready.
+
+## Spec Contents
+
+Each spec should include:
+
+- goal
+- background
+- users and stakeholders
+- in-scope behavior
+- out-of-scope items
+- acceptance criteria
+- risks and assumptions
+- open questions
+- next command
+