ai-core-framework 0.1.0

package/core/skills/planning-document-existing-requirements/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: planning-document-existing-requirements
+description: Use when the user asks to run /document-existing-requirements, document requirements for an existing feature, infer current behavior from code, or create requirements docs from an implemented module.
+command: /document-existing-requirements
+display_name: "Document Existing Requirements"
+version: 1.0.0
+owner_agent: business-analyst
+requires_agents:
+  - business-analyst
+consults_agents:
+  - tech-lead
+  - developer
+model_preference: opus
+args:
+  - name: scope
+    required: true
+    type: string
+    description: "Existing feature/module/path to analyze, for example auth, billing, src/app/login"
+  - name: output_path
+    required: false
+    type: string
+    default: "docs/project/requirements/<scope>-requirements.md"
+    description: "Requirement documentation path"
+  - name: create_tickets
+    required: false
+    type: boolean
+    default: false
+    description: "Whether to create follow-up tickets for discovered gaps"
+preconditions:
+  - ai_core_initialized: true
+  - source_code_available: true
+  - business_analyst_agent_available: true
+postconditions:
+  - requirements_doc_created: true
+  - evidence_links_included: true
+  - inferred_requirements_marked: true
+---
+
+# /document-existing-requirements
+
+> Analyze existing source code and write requirement documentation for behavior that already exists.
+> This command is for reverse-documenting current product behavior, not inventing new requirements.
+
+## 🎯 Purpose
+
+Create a requirements document from existing implementation evidence:
+- Current user-facing behavior
+- Personas and user goals visible from code
+- Acceptance Criteria derived from routes, UI, tests, validators, and error handling
+- Business rules implemented in source code
+- Edge cases and constraints already enforced
+- Documentation gaps, ambiguity, and follow-up questions
+
+## 🚦 Trigger
+
+**Manual**:
+```text
+/document-existing-requirements auth
+/document-existing-requirements src/app/login
+/document-existing-requirements --output_path=docs/project/requirements/auth-requirements.md auth
+```
+
+## 📋 Preconditions (STRICT)
+
+Check before starting. **ABORT** if any check fails.
+
+### 1. Source code exists
+At least one implementation path must exist under `src/`, `app/`, `lib/`, or the project-specific source root.
+
+### 2. Scope is explicit
+`scope` **MUST** identify a feature, module, route, or path. Vague scopes such as "the app" are **FORBIDDEN** unless the repository is very small.
+
+### 3. Output path is allowed
+Output **MUST** be written under `docs/project/requirements/` unless the user explicitly provides another documentation path allowed by project rules.
+
+## 🔄 Execution Flow (STRICT ORDER)
+
+```
+┌──────────────────────────────────────────────────────────┐
+│ STEP 1: Resolve scope                                    │
+│   - Map scope to files, routes, components, tests        │
+│   - Identify entrypoints and user-facing surfaces        │
+├──────────────────────────────────────────────────────────┤
+│ STEP 2: Gather evidence                                  │
+│   - Read implementation files                            │
+│   - Read tests and fixtures                              │
+│   - Read API route handlers and validators               │
+│   - Read UI copy, forms, states, and error messages      │
+│   - Read existing docs/ADRs when relevant                │
+├──────────────────────────────────────────────────────────┤
+│ STEP 3: Extract observed behavior                         │
+│   - List capabilities proven by code                     │
+│   - List inputs, outputs, states, permissions            │
+│   - List validation, errors, limits, and side effects    │
+├──────────────────────────────────────────────────────────┤
+│ STEP 4: Derive requirements                               │
+│   - Convert observed behavior into User Stories          │
+│   - Convert branches/tests/errors into AC scenarios      │
+│   - Mark each requirement as OBSERVED or INFERRED        │
+├──────────────────────────────────────────────────────────┤
+│ STEP 5: Identify gaps                                     │
+│   - Missing tests                                        │
+│   - Unclear behavior                                     │
+│   - Inconsistent UI/API behavior                         │
+│   - Business rules implemented but undocumented          │
+├──────────────────────────────────────────────────────────┤
+│ STEP 6: Write requirements document                       │
+│   - Path: docs/project/requirements/<scope>-requirements.md      │
+│   - Include evidence links for every observed claim      │
+│   - Include open questions                               │
+├──────────────────────────────────────────────────────────┤
+│ STEP 7: Optional follow-up tickets                        │
+│   - Only if create_tickets=true                          │
+│   - Create tickets for gaps, missing tests, ambiguities  │
+└──────────────────────────────────────────────────────────┘
+```
+
+## 🔒 Hard Rules
+
+### RULE DER-001: Evidence required
+Every observed requirement **MUST** cite source evidence using file paths and, when possible, line references. Claims without evidence **MUST** be marked `INFERRED` or moved to Open Questions.
+
+### RULE DER-002: No invented product behavior
+The agent **MUST NOT** invent behavior that is not visible in source code, tests, docs, or configuration. If behavior seems likely but is not proven, mark it `INFERRED`.
+
+### RULE DER-003: Separate observed vs inferred
+The output **MUST** separate:
+- `OBSERVED`: directly supported by source evidence
+- `INFERRED`: likely but not directly proven
+- `UNKNOWN`: cannot be determined from code
+
+### RULE DER-004: No production code changes
+This command **MUST NOT** modify production code. It may write docs under `docs/project/requirements/` and optionally create project tickets when `create_tickets=true`.
+
+### RULE DER-005: Tests are evidence, not truth alone
+Tests may prove intended behavior, but the agent **MUST** compare tests with implementation. If tests and code disagree, document the disagreement as a gap.
+
+### RULE DER-006: Preserve implementation neutrality
+Requirement text **MUST** describe WHAT the system does and WHY it matters. It **MUST NOT** prescribe HOW to refactor or implement unless listing technical evidence.
+
+### RULE DER-007: Ask when scope is unsafe
+If the requested scope is too broad to analyze reliably, the agent **MUST** stop and ask for a narrower module, route, or feature area.
+
+## 📤 Output Document Template
+
+````markdown
+# Requirements: <Feature / Scope>
+
+**Source scope**: `<scope>`
+**Generated by**: business-analyst-agent
+**Generated at**: <timestamp>
+**Status**: Reverse-documented from existing source code
+
+## Summary
+[Short description of current behavior]
+
+## Evidence Map
+| Area | Files |
+|------|-------|
+| Routes/API | `path/to/file` |
+| UI | `path/to/file` |
+| Tests | `path/to/file` |
+| Config/Policies | `path/to/file` |
+
+## Personas
+- [OBSERVED] As a <persona> ...
+- [INFERRED] As a <persona> ...
+
+## User Stories
+
+### US-001: <Title>
+**Status**: OBSERVED | INFERRED
+**Evidence**:
+- `path/to/file`
+
+**As a** <persona>
+**I want** <action>
+**So that** <value>
+
+### Acceptance Criteria
+
+**Scenario 1: <Happy path>**
+```gherkin
+Given ...
+When ...
+Then ...
+````
+
+## Business Rules
+| Rule | Status | Evidence |
+|------|--------|----------|
+| <rule> | OBSERVED | `path/to/file` |
+
+## Edge Cases & Error Handling
+| Case | Behavior | Evidence |
+|------|----------|----------|
+| <case> | <behavior> | `path/to/file` |
+
+## Non-Functional Requirements
+- Performance:
+- Security:
+- Accessibility:
+- Observability:
+
+## Gaps / Ambiguities
+- [UNKNOWN] <question or missing evidence>
+- [MISMATCH] <test/code/doc disagreement>
+
+## Follow-Up Recommendations
+- Create ticket for <gap>
+- Add test for <behavior>
+```
+
+## 📥 Input Examples
+
+### Module
+```text
+/document-existing-requirements auth
+```
+
+### Route path
+```text
+/document-existing-requirements src/app/login
+```
+
+### With explicit output path
+```text
+/document-existing-requirements --output_path=docs/project/requirements/password-reset.md auth/password-reset
+```
+
+## 🚫 Failure Modes
+
+| Failure | Required action |
+|---------|-----------------|
+| Scope too broad | ABORT and ask for narrower scope |
+| No matching files | ABORT and report searched paths |
+| Evidence insufficient | Write only OBSERVED claims and list UNKNOWN items |
+| Tests contradict implementation | Document mismatch and recommend follow-up |
+| Output path outside docs | ABORT unless explicitly allowed by project rules |
+
+## 🔗 Related Commands
+
+- `/discover-codebase` - map modules before requirement extraction
+- `/analyze-requirements` - create new requirements from stakeholder input
+- `/groom-ticket` - refine tickets created from discovered gaps
+- `/write-plan` - create implementation plan after requirements are accepted

package/core/skills/planning-estimate-task/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: planning-estimate-task
+description: Use when the user asks to run /estimate-task, estimate a ticket, update story points, compare implementation complexity, or sanity-check effort with technical and product context.
+command: /estimate-task
+display_name: "Estimate Task"
+version: 1.0.0
+status: READY
+owner_agent: tech-lead
+consults_agents:
+  - developer
+  - business-analyst
+model_preference: sonnet
+args:
+  - name: ticket_id
+    required: true
+    format: "TICKET-XXX"
+preconditions:
+  - ticket_exists: true
+  - ticket_has_acceptance_criteria: true
+postconditions:
+  - estimate_updated: true
+---
+
+# /estimate-task
+
+> Estimates or re-estimates a ticket using evidence, complexity factors, and Fibonacci points.
+
+## 🎯 Purpose
+
+Provide a traceable estimate for planning and detect tickets that need splitting.
+
+## 🔄 Execution Flow
+
+1. Load ticket, AC, technical notes, and previous estimates.
+2. Inspect related code or past similar tickets.
+3. Identify complexity drivers, risks, dependencies, and unknowns.
+4. Select Fibonacci estimate: 1, 2, 3, 5, or 8.
+5. If larger than 8, recommend split instead of estimating higher.
+6. Update `estimate` and add comment with rationale.
+7. Run `/validate-state`.
+
+## 🔒 Hard Rules
+
+- MUST cite evidence and complexity factors.
+- MUST NOT estimate above 8 for sprint work.
+- MUST NOT change BA-owned acceptance criteria.
+- MUST re-check DoR if estimate changes after `READY`.
+
+## 📤 Outputs
+
+- Story point estimate
+- Rationale
+- Risks and unknowns
+- Split recommendation if needed
+
+## 🔗 Related Commands
+
+- `/groom-ticket`
+- `/mark-ready`
+- `/plan-sprint`