raptor-aios 0.1.0

package/templates/commands/implement.md

@@ -0,0 +1,117 @@
+---
+description: Execute tasks from tasks.md and write implementation code
+handoffs:
+  - label: Generate checklist
+    agent: rpt.checklist
+    prompt: "Generate quality checklist post-implementation"
+    send: false
+  - label: Analyze consistency
+    agent: rpt.analyze
+    prompt: "Verify implementation matches spec"
+    send: false
+scripts:
+  sh: scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks
+---
+
+<!-- prompt-version: 1.0.0 -->
+
+# /rpt.implement
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+## Pre-Execution Checks
+
+1. Read `.raptor/extensions.yml` (if present).
+2. For each hook registered under `before_implement`:
+   - If `optional: false` → execute `EXECUTE_COMMAND: <command>` and wait.
+   - If `optional: true` → suggest `/<command>` to the user.
+3. If `.raptor/extensions.yml` is absent or invalid, proceed silently.
+
+## Outline
+
+1. **Setup**: Run `{SCRIPT}` from repo root. Parse JSON for `FEATURE_DIR`, `AVAILABLE_DOCS`.
+2. **Load context**: Read spec.md, plan.md, data-model.md, contracts/, tasks.md.
+3. **Verify checklists**: If `checklists/requirements.md` is incomplete, ask before proceeding.
+4. **Create ignore files**: Generate `.gitignore`, `.dockerignore`, etc. based on stack in plan.md.
+5. **Execute tasks**: Loop through tasks.md, respecting phase order and parallelization.
+6. **Validate**: Compare implementation against spec success criteria.
+
+## Execution Rules (NON-NEGOTIABLE)
+
+### Phase Order
+
+Complete ALL tasks in Phase N before starting Phase N+1. Verify completion before advancing.
+
+### Parallelization
+
+Tasks marked `[P]` that operate on DIFFERENT files with NO dependencies may be executed simultaneously.
+Tasks on the SAME file MUST be sequential.
+
+### TDD Mode
+
+If the spec or plan specifies TDD:
+
+1. Write the test FIRST
+2. Run the test (it should fail)
+3. Write the implementation
+4. Run the test (it should pass)
+
+### Progress Tracking
+
+After completing each task:
+
+1. Change `- [ ]` to `- [X]` in `tasks.md`
+2. Save the file immediately
+3. Continue to next task
+
+### Resumption
+
+When re-executing `/rpt.implement`:
+
+1. Read `tasks.md`
+2. Skip all `[X]` (completed) tasks
+3. Resume from the first `[ ]` (uncompleted) task
+4. Do NOT re-execute completed tasks
+
+### Ignore Files
+
+Based on the tech stack detected in `plan.md`, create/verify:
+
+- `.gitignore` — standard patterns for the stack
+- `.dockerignore` — if Docker is used
+- `.eslintignore` — if ESLint is used
+- `.prettierignore` — if Prettier is used
+
+Only create files that don't already exist. Append patterns to existing files if needed.
+
+## Validation
+
+After all tasks are complete:
+
+1. **Spec compliance**: Read `spec.md` acceptance criteria. For each criterion:
+   - Mark as ✅ (met) or ❌ (gap).
+   - For gaps, explain what's missing and what task would fix it.
+
+2. **Test execution**: If tests are defined, run them and report results.
+
+3. **Implementation report**: Generate a summary in the conversation:
+
+   ```
+   Implementation Complete:
+   - Tasks: X/Y completed
+   - Spec criteria: A/B met
+   - Tests: P passed, F failed
+   - Gaps: [list if any]
+   ```
+
+## Final Hook Check
+
+1. Read `.raptor/extensions.yml` (if present).
+2. For each hook registered under `after_implement`:
+   - If `optional: false` → execute `EXECUTE_COMMAND: <command>` and wait.
+   - If `optional: true` → suggest `/<command>` to the user.
+3. If `.raptor/extensions.yml` is absent or invalid, proceed silently.

package/templates/commands/plan.md

@@ -0,0 +1,125 @@
+---
+description: Generate implementation plan with research, data model, contracts, and quickstart
+handoffs:
+  - label: Generate tasks
+    agent: rpt.tasks
+    prompt: "Break the plan into implementable tasks"
+    send: false
+  - label: Analyze consistency
+    agent: rpt.analyze
+    prompt: "Analyze consistency between spec and plan"
+    send: false
+scripts:
+  sh: scripts/bash/setup-plan.sh --json
+---
+
+<!-- prompt-version: 1.0.0 -->
+
+# /rpt.plan
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+## Pre-Execution Checks
+
+1. Read `.raptor/extensions.yml` (if present).
+2. For each hook registered under `before_plan`:
+   - If `optional: false` → execute `EXECUTE_COMMAND: <command>` and wait.
+   - If `optional: true` → suggest `/<command>` to the user.
+3. If `.raptor/extensions.yml` is absent or invalid, proceed silently.
+
+## Outline
+
+1. **Setup**: Run `{SCRIPT}` from repo root. Parse JSON for `FEATURE_SPEC`, `IMPL_PLAN`, `SPECS_DIR`, `BRANCH`, `HAS_GIT`.
+2. **Load context**: Read `FEATURE_SPEC` (spec.md) and `.raptor/memory/constitution.md`.
+3. **Fill plan**: Write `plan.md` with Technical Context + Constitution Check (initial).
+4. **Phase 0**: Generate `research.md` resolving unknowns from the spec.
+5. **Phase 1**: Generate `data-model.md`, `contracts/`, `quickstart.md`.
+6. **Update context file**: Write between `<!-- RAPTOR START -->` / `<!-- RAPTOR END -->` markers in `__CONTEXT_FILE__`.
+7. **Post-design Constitution Check**: Re-evaluate all principles after design.
+
+## Phases
+
+### Phase 0 — Research
+
+Read `spec.md` and identify technical unknowns (libraries, APIs, patterns, constraints).
+
+Generate `<FEATURE_DIR>/research.md`:
+
+- External dependencies to evaluate
+- API documentation summaries
+- Pattern recommendations
+- Performance considerations
+- Security implications
+
+### Phase 1 — Technical Design
+
+Generate the following artifacts:
+
+**`<FEATURE_DIR>/data-model.md`**:
+
+- Entity definitions (fields, types, constraints)
+- Relationships (1:1, 1:N, N:N)
+- Lifecycle (creation, mutation, deletion)
+- Indexes and performance considerations
+
+**`<FEATURE_DIR>/contracts/`**:
+
+- API endpoint definitions (REST/GraphQL/gRPC)
+- Event schemas
+- Deep link definitions
+- External service contracts
+
+**`<FEATURE_DIR>/quickstart.md`**:
+
+- Step-by-step setup guide
+- Development environment requirements
+- Configuration needed
+- First-run instructions
+
+### Phase 2 — Plan Authoring
+
+Fill `plan.md` sections:
+
+1. Context & Constraints
+2. Architecture Overview (include mermaid diagram)
+3. Data Model (reference `data-model.md`)
+4. Contracts (reference `contracts/`)
+5. Decisions (numbered, with rationale)
+6. Alternatives considered
+7. Risks & Mitigations
+8. Rollout & Reversibility
+9. Observability
+
+### Phase 3 — Constitution Check
+
+**Initial Check**: Read `.raptor/memory/constitution.md`. For each principle, evaluate compatibility with the design. Fill the "Initial Check" table in `plan.md`.
+
+**Post-Design Check**: After all design artifacts are generated, re-evaluate each principle. Fill the "Post-Design Check" table. Flag any newly introduced violations.
+
+### Phase 4 — Context File Update
+
+Update `__CONTEXT_FILE__` between markers:
+
+```markdown
+<!-- RAPTOR START -->
+## Active Feature: <feature-name>
+
+- Spec: specs/<feature>/spec.md
+- Plan: specs/<feature>/plan.md
+- Status: planning
+<!-- RAPTOR END -->
+```
+
+Insertion must be **idempotent** — replace existing block if markers already exist.
+
+## Final Hook Check
+
+1. Read `.raptor/extensions.yml` (if present).
+2. For each hook registered under `after_plan`:
+   - If `optional: false` → execute `EXECUTE_COMMAND: <command>` and wait.
+   - If `optional: true` → suggest `/<command>` to the user.
+3. If `.raptor/extensions.yml` is absent or invalid, proceed silently.

package/templates/commands/specify.md

@@ -0,0 +1,127 @@
+---
+description: Create or update a feature specification from a natural language description
+handoffs:
+  - label: Clarify ambiguities
+    agent: rpt.clarify
+    prompt: "Clarify the open questions in the spec"
+    send: false
+  - label: Plan the implementation
+    agent: rpt.plan
+    prompt: "Create an implementation plan based on the spec"
+    send: false
+scripts:
+  sh: scripts/bash/create-new-feature.sh --json
+---
+
+<!-- prompt-version: 1.0.0 -->
+
+# /rpt.specify
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+## Pre-Execution Checks
+
+1. Read `.raptor/extensions.yml` (if present).
+2. For each hook registered under `before_specify`:
+   - If `optional: false` → execute `EXECUTE_COMMAND: <command>` and wait for completion.
+   - If `optional: true` → render suggestion button `/<command>`.
+   - If `enabled: false` → skip silently.
+3. If `.raptor/extensions.yml` is absent or invalid, proceed silently.
+
+## Outline
+
+1. **Setup**: Run `{SCRIPT}` from repo root and parse JSON for `BRANCH_NAME`, `FEATURE_NUM`, `FEATURE_DIR`.
+2. **Resolve directory**: Set `RAPTOR_FEATURE_DIRECTORY` to the resolved `FEATURE_DIR`.
+3. **Create spec directory**: Ensure `specs/<FEATURE_DIR>/` exists.
+4. **Copy template**: Resolve `spec-template.md` via priority stack and copy to `<FEATURE_DIR>/spec.md`.
+5. **Parse description**: Transform user's natural language description (`$ARGUMENTS`) into structured spec sections.
+6. **Auto-validate**: Up to 3 self-validation iterations. Mark `[NEEDS CLARIFICATION]` for genuinely ambiguous items (max 3).
+7. **Generate checklist**: Create `<FEATURE_DIR>/checklists/requirements.md` with quality gates.
+8. **Persist state**: Write/update `.raptor/feature.json` with `{"feature_directory": "<FEATURE_DIR>"}`.
+
+## Phases
+
+### Phase 0 — Feature Branch & Directory
+
+Run `{SCRIPT}` with `{ARGS}` from the repository root. Parse the JSON output:
+
+```json
+{
+  "BRANCH_NAME": "003-user-auth",
+  "FEATURE_NUM": "003",
+  "FEATURE_DIR": "specs/003-user-auth"
+}
+```
+
+Create the spec directory if it doesn't exist.
+
+### Phase 1 — Spec Template Resolution
+
+Resolve `spec-template.md` using the priority stack:
+
+1. `.raptor/templates/overrides/spec-template.md`
+2. `.raptor/presets/<id>/templates/spec-template.md`
+3. `.raptor/extensions/<id>/templates/spec-template.md`
+4. `.raptor/templates/spec-template.md`
+
+Copy the resolved template to `<FEATURE_DIR>/spec.md`.
+
+### Phase 2 — Specification Authoring
+
+Transform `$ARGUMENTS` into structured spec sections:
+
+- **Summary**: One-paragraph description of the feature.
+- **User Stories**: Formatted as `As a <role>, I want to <action>, so that <benefit>`.
+- **Acceptance Criteria**: Given/When/Then format.
+- **Technical Constraints**: Architecture boundaries, dependencies, non-functional requirements.
+- **Out of Scope**: Explicit exclusions.
+
+Rules:
+
+- Mark genuinely ambiguous items as `[NEEDS CLARIFICATION: <question>]` (max 3 total).
+- Do NOT invent requirements — only capture what is in `$ARGUMENTS` and reasonable inferences.
+- Prefer concrete, testable criteria over vague descriptions.
+
+### Phase 3 — Self-Validation
+
+Perform up to 3 iterations:
+
+1. Re-read the generated spec.
+2. Check for internal contradictions, missing acceptance criteria, and unclear scope.
+3. Fix any issues found.
+4. If `[NEEDS CLARIFICATION]` items remain after 3 iterations, present a Q&A table to the user.
+
+### Phase 4 — Quality Gate Checklist
+
+Create `<FEATURE_DIR>/checklists/requirements.md`:
+
+```markdown
+# Requirements Checklist — <feature-name>
+
+- [ ] All user stories have acceptance criteria
+- [ ] Non-functional requirements are specified (performance, security, accessibility)
+- [ ] Dependencies are listed
+- [ ] Out-of-scope is explicit
+- [ ] No more than 3 [NEEDS CLARIFICATION] items
+- [ ] Spec is self-consistent (no contradictions)
+```
+
+### Phase 5 — State Persistence
+
+Write `.raptor/feature.json`:
+
+```json
+{ "feature_directory": "<FEATURE_DIR>" }
+```
+
+## Final Hook Check
+
+1. Read `.raptor/extensions.yml` (if present).
+2. For each hook registered under `after_specify`:
+   - If `optional: false` → execute `EXECUTE_COMMAND: <command>` and wait.
+   - If `optional: true` → suggest `/<command>` to the user.
+3. If `.raptor/extensions.yml` is absent or invalid, proceed silently.

package/templates/commands/tasks.md

@@ -0,0 +1,98 @@
+---
+description: Break implementation plan into strict checklist tasks
+handoffs:
+  - label: Implement tasks
+    agent: rpt.implement
+    prompt: "Execute the tasks and write code"
+    send: false
+  - label: Analyze consistency
+    agent: rpt.analyze
+    prompt: "Verify tasks align with spec and plan"
+    send: false
+scripts:
+  sh: scripts/bash/check-prerequisites.sh --json
+---
+
+<!-- prompt-version: 1.0.0 -->
+
+# /rpt.tasks
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+## Pre-Execution Checks
+
+1. Read `.raptor/extensions.yml` (if present).
+2. For each hook registered under `before_tasks`:
+   - If `optional: false` → execute `EXECUTE_COMMAND: <command>` and wait.
+   - If `optional: true` → suggest `/<command>` to the user.
+3. If `.raptor/extensions.yml` is absent or invalid, proceed silently.
+
+## Outline
+
+1. **Setup**: Run `{SCRIPT}` from repo root. Parse JSON for `FEATURE_DIR`, `AVAILABLE_DOCS`.
+2. **Load all artifacts**: Read spec.md, plan.md, research.md, data-model.md, contracts/, quickstart.md.
+3. **Map user stories**: Extract user stories from spec.md and classify as P1/P2/P3.
+4. **Generate tasks**: Create `tasks.md` in strict checklist format.
+
+## Task Format (NON-NEGOTIABLE)
+
+Each task line MUST follow this format:
+
+```
+- [ ] T<NNN> <Description with explicit file path>
+- [ ] T<NNN> [P] <Description in src/path/file.ts>
+- [ ] T<NNN> [P] [US<N>] <Description in src/path/file.ts>
+```
+
+Components:
+
+- `[ ]` / `[X]` — checkbox (unchecked / completed)
+- `T<NNN>` — sequential ID (T001, T002, ...)
+- `[P]` — parallelizable (optional): task can run alongside other `[P]` tasks in same phase
+- `[US<N>]` — user story reference (optional): links to spec user story
+- Description MUST include explicit file path
+
+## Phase Structure
+
+Tasks MUST be organized in phases:
+
+```markdown
+## Phase 1: Setup
+- [ ] T001 Initialize project structure in src/
+- [ ] T002 [P] Install dependencies in package.json
+
+## Phase 2: Foundational
+- [ ] T003 Create base types in src/types/index.ts
+- [ ] T004 [P] Create database schema in src/db/schema.ts
+
+## Phase 3: User Stories (P1)
+- [ ] T005 [US1] Implement user registration in src/auth/register.ts
+- [ ] T006 [P] [US1] Create registration form in src/ui/RegisterForm.tsx
+
+## Phase 4: User Stories (P2)
+- [ ] T010 [US3] Add profile editing in src/profile/edit.ts
+
+## Phase N: Polish & Cross-cutting
+- [ ] T020 Add error handling across src/
+- [ ] T021 [P] Add logging in src/utils/logger.ts
+```
+
+## Rules
+
+1. **Each task must be self-sufficient** for an LLM to implement in isolation.
+2. **Description + path**: every task references a concrete file.
+3. **Order matters**: Phase N depends on Phase N-1 being complete.
+4. **Parallel `[P]`**: only between tasks that touch DIFFERENT files with no deps.
+5. **Granularity**: one task = one prompt = one coherent change.
+
+## Final Hook Check
+
+1. Read `.raptor/extensions.yml` (if present).
+2. For each hook registered under `after_tasks`:
+   - If `optional: false` → execute `EXECUTE_COMMAND: <command>` and wait.
+   - If `optional: true` → suggest `/<command>` to the user.
+3. If `.raptor/extensions.yml` is absent or invalid, proceed silently.

package/templates/commands/taskstoissues.md

@@ -0,0 +1,81 @@
+---
+description: Convert the generated task list into tracker issues (GitHub by default) for execution and tracking
+handoffs:
+  - label: Implement the tasks
+    agent: rpt.implement
+    prompt: "Execute the tasks from tasks.md"
+    send: false
+scripts:
+  sh: scripts/bash/check-prerequisites.sh --json
+---
+
+<!-- prompt-version: 1.0.0 -->
+
+# /rpt.taskstoissues
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+## Pre-Execution Checks
+
+1. Read `.raptor/extensions.yml` (if present).
+2. For each hook registered under `before_taskstoissues`:
+   - If `optional: false` → execute `EXECUTE_COMMAND: <command>` and wait for completion.
+   - If `optional: true` → render suggestion button `/<command>`.
+   - If `enabled: false` → skip silently.
+3. If `.raptor/extensions.yml` is absent or invalid, proceed silently.
+
+## Outline
+
+1. **Setup**: Run `{SCRIPT}` and parse JSON for `FEATURE_DIR` and the available docs.
+2. **Locate tasks**: Read `<FEATURE_DIR>/tasks.md`; require `status: approved` in its frontmatter.
+3. **Detect tracker**: Resolve the remote (`git config --get remote.origin.url`). If no remote, STOP and tell the user to add one or choose a tracker.
+4. **Create one issue per task**: Preserve task order and dependencies; carry the `[US#]`/`[P]` tags into labels.
+5. **Link back**: Record the created issue ids/URLs next to each task in `tasks.md` (or an `issues.md` map).
+
+## Phases
+
+### Phase 0 — Prerequisites
+
+Run `{SCRIPT}` from the repository root and parse the JSON. Resolve `FEATURE_DIR`
+and confirm `tasks.md` exists and is approved.
+
+### Phase 1 — Tracker Resolution
+
+Determine the target tracker:
+
+- **GitHub (default)**: confirm `git config --get remote.origin.url` points to a
+  GitHub repository. Use the available GitHub MCP server / `gh` CLI to create issues.
+- **Jira (optional)**: only if a Jira extension is configured in `.raptor/extensions.yml`.
+- If neither is available, STOP with a clear message — do NOT fabricate issue ids.
+
+### Phase 2 — Issue Creation
+
+For each task `T###` in `tasks.md`, in dependency order:
+
+1. Title: `T### — <task description>`.
+2. Body: the task's acceptance intent + a back-link to `<FEATURE_DIR>/tasks.md` and the spec.
+3. Labels: the user story tag(s) (`US#`), `parallel` when `[P]`, and the feature slug.
+4. Create the issue via the resolved tracker.
+
+Rules:
+
+- One issue per task — do NOT batch.
+- Preserve order; if task B depends on A, note the dependency in B's body.
+- Be idempotent: if an issue for a task already exists (recorded in the map), skip it.
+
+### Phase 3 — Back-Reference
+
+Write `<FEATURE_DIR>/issues.md` mapping each `T###` to its created issue id/URL,
+so re-runs are idempotent and `implement` can reference them.
+
+## Final Hook Check
+
+1. Read `.raptor/extensions.yml` (if present).
+2. For each hook registered under `after_taskstoissues`:
+   - If `optional: false` → execute `EXECUTE_COMMAND: <command>` and wait.
+   - If `optional: true` → suggest `/<command>` to the user.
+3. If `.raptor/extensions.yml` is absent or invalid, proceed silently.

package/templates/constitution-template.md

@@ -0,0 +1,48 @@
+# Constitution — {{ projectName }}
+
+> **Version**: 1.0.0
+> **Created**: {{ createdAt }}
+> **Last Updated**: {{ createdAt }}
+> **Preset**: {{ preset }}
+
+---
+
+## Core Principles
+
+These principles are non-negotiable. Violating any principle without explicit justification is an ERROR that blocks the pipeline.
+
+### [PRINCIPLE_1_NAME]
+
+[PRINCIPLE_1_DESCRIPTION]
+
+### [PRINCIPLE_2_NAME]
+
+[PRINCIPLE_2_DESCRIPTION]
+
+### [PRINCIPLE_3_NAME]
+
+[PRINCIPLE_3_DESCRIPTION]
+
+---
+
+## [SECTION_NAME]
+
+> Add project-specific sections below. Each section codifies a class of
+> architectural decisions that the team considers immutable.
+
+### [SECTION_PRINCIPLE_1_NAME]
+
+[SECTION_PRINCIPLE_1_DESCRIPTION]
+
+---
+
+## Ratification History
+
+| Version | Date | Author | Change |
+|---------|------|--------|--------|
+| 1.0.0   | {{ createdAt }} | System | Initial constitution created via `raptor init` |
+
+---
+
+<!-- RAPTOR-CONSTITUTION-FOOTER -->
+<!-- Do not edit below this line. Managed by /rpt.constitution -->