@codifier/cli 2.0.0

package/skills/initialize-project/templates/evals-prompt.md

@@ -0,0 +1,39 @@
+# Prompt Template: Generate Evals.md
+
+When this template is used, substitute all `{placeholders}` with actual values, then generate the evals document as instructed.
+
+---
+
+You are a quality-engineering expert. Using the project rules below, create a set of structured evaluation criteria that can be used to verify compliance with those rules during code review, CI checks, or AI-assisted development sessions.
+
+## Project Rules
+
+{rules}
+
+## Project Context
+
+**Project Name:** {project_name}
+**Description:** {description}
+
+## Instructions
+
+For EACH rule, produce one or more evals. Each eval must include:
+
+- **id**: a slug identifier (e.g., `eval-validate-input-boundary`)
+- **rule_ref**: the title or ID of the rule being evaluated
+- **description**: what this eval checks
+- **pass_criteria**: precise, observable conditions that indicate the rule is being followed
+- **fail_criteria**: precise, observable conditions that indicate a violation
+- **automation_hint**: whether this can be checked automatically (lint, test, static analysis) and how
+
+Format the output as a YAML document with a top-level `evals:` list. Example structure:
+
+```yaml
+evals:
+  - id: eval-validate-input-boundary
+    rule_ref: Always validate external input at the boundary
+    description: Checks that all external inputs are validated before use
+    pass_criteria: Every controller method validates request body with a schema before processing
+    fail_criteria: Business logic receives raw unvalidated input from request objects
+    automation_hint: ESLint rule or custom AST check; unit tests covering invalid inputs
+```

package/skills/initialize-project/templates/requirements-prompt.md

@@ -0,0 +1,44 @@
+# Prompt Template: Generate Requirements.md
+
+When this template is used, substitute all `{placeholders}` with actual values, then generate the requirements document as instructed.
+
+---
+
+You are a product manager and solutions architect. Using the project information below, produce a detailed requirements document.
+
+## Project Information
+
+**Project Name:** {project_name}
+**Description:** {description}
+**Scope of Work:** {sow}
+**Repositories:** {repo_urls}
+**Additional Context:** {additional_context}
+
+## Instructions
+
+Produce a requirements document titled `# Requirements.md` with the following sections:
+
+### 1. Executive Summary
+One-paragraph summary of what the project delivers and for whom.
+
+### 2. Functional Requirements
+List every distinct feature or capability. For each requirement use this format:
+
+- **FR-001**: short title
+  - **Priority**: Must / Should / Could (MoSCoW)
+  - **Description**: what the system must do
+  - **Acceptance Criteria**: measurable, testable conditions
+
+### 3. Non-Functional Requirements
+Cover: Performance, Security, Scalability, Reliability, Maintainability, Observability. Use the same FR-NNN format with prefix NFR-.
+
+### 4. Constraints and Assumptions
+List known technical constraints, business constraints, and assumptions being made.
+
+### 5. Out of Scope
+Explicitly list what is NOT included in this project.
+
+### 6. Glossary
+Define key domain terms used throughout this document.
+
+Format as a structured Markdown document. Number all requirements sequentially.

package/skills/initialize-project/templates/roadmap-prompt.md

@@ -0,0 +1,44 @@
+# Prompt Template: Generate Roadmap.md
+
+When this template is used, substitute all `{placeholders}` with actual values, then generate the roadmap document as instructed.
+
+---
+
+You are a senior engineering lead responsible for delivery planning. Using the project requirements below, produce a phased implementation roadmap.
+
+## Requirements
+
+{requirements}
+
+## Project Context
+
+**Project Name:** {project_name}
+**Description:** {description}
+**Repositories:** {repo_urls}
+
+## Instructions
+
+Produce a roadmap titled `# Roadmap.md` structured as 3–5 phases. For EACH phase include:
+
+- **Phase N — Name**: meaningful phase title (e.g., "Phase 1 — Foundation")
+- **Goal**: one-sentence summary of what this phase achieves
+- **Duration estimate**: calendar weeks or sprints
+- **Deliverables**: concrete, shippable outputs
+- **Functional Requirements covered**: list the FR-NNN and NFR-NNN IDs addressed
+- **Technical tasks**: engineering work breakdown (checklist format)
+- **Dependencies**: what must be true before this phase can start
+- **Success criteria**: how to know this phase is done
+
+After the phased plan, include:
+
+### Critical Path
+The sequence of tasks where any delay directly delays the project.
+
+### Risks and Mitigations
+Top 5 risks in a table:
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|-----------|
+| ... | High/Med/Low | High/Med/Low | ... |
+
+Format as a structured Markdown document.

package/skills/initialize-project/templates/rules-prompt.md

@@ -0,0 +1,34 @@
+# Prompt Template: Generate Rules.md
+
+When this template is used, substitute all `{placeholders}` with actual project values, then generate the rules document as instructed.
+
+---
+
+You are a senior software architect. Based on the project context below, generate a comprehensive set of development rules and coding standards for this project.
+
+## Project Context
+
+**Project Name:** {project_name}
+**Description:** {description}
+**Scope of Work:** {sow}
+**Repositories:** {repo_urls}
+**Additional Context:** {additional_context}
+
+## Instructions
+
+Generate rules covering ALL of the following areas:
+
+1. **Code Style** — naming conventions, file organisation, formatting
+2. **Architecture Patterns** — module structure, dependency direction, layering
+3. **Security** — input validation, secrets management, authentication patterns
+4. **Testing** — unit test structure, coverage targets, mocking strategy
+5. **Documentation** — inline comments, ADR conventions, README standards
+6. **Error Handling** — error propagation, logging strategy, user-facing messages
+
+For EACH rule provide:
+- **title**: short, actionable slug (e.g., "Always validate external input at the boundary")
+- **description**: one-paragraph explanation
+- **rationale**: why this rule matters for this specific project
+- **examples**: 1–3 concrete code or configuration examples
+
+Format the output as a Markdown document titled `# Rules.md` with one H2 heading per rule category and one H3 heading per rule.

package/skills/research-analyze/SKILL.md

@@ -0,0 +1,131 @@
+# Skill: Research & Analyze
+
+**Role:** Researcher
+**Purpose:** Define a research objective, discover Athena data warehouse schemas, generate and validate SQL queries, execute them, synthesize the findings into a ResearchFindings.md report, and persist it to the shared knowledge base.
+
+See `../shared/codifier-tools.md` for full MCP tool reference.
+
+---
+
+## Prerequisites
+
+- Active MCP connection to the Codifier server
+- AWS Athena credentials configured on the server (`AWS_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `ATHENA_S3_OUTPUT_LOCATION`)
+- A project to associate the findings with
+
+---
+
+## Workflow
+
+### Step 1 — Identify or Create the Project
+
+Call `manage_projects` with `operation: "list"` and show the user their existing projects.
+
+Ask: **"Which project should these research findings be associated with?"**
+
+Select or create a project and capture the `project_id`.
+
+### Step 2 — Fetch Prior Research
+
+Call `fetch_context` with `{ project_id, memory_type: "research_finding" }` to surface any prior findings relevant to this session.
+
+If prior findings exist, summarize them briefly: **"Here's what we've found before on this project..."**
+
+### Step 3 — Define the Research Objective
+
+Ask the user to describe:
+1. **Research objective** — the specific question or hypothesis to investigate
+2. **Background context** — business context, prior hypotheses, relevant metrics or KPIs
+3. **Time period of interest** — date ranges for the analysis
+4. **Known relevant tables** — if the user knows which tables to look at (optional)
+
+Confirm your understanding of the objective before proceeding.
+
+### Step 4 — Discover Available Tables
+
+Call `query_data` with `{ operation: "list-tables", project_id }`.
+
+Present the full table list to the user. Ask: **"Which of these tables are likely relevant to your research objective?"**
+
+### Step 5 — Describe Selected Tables
+
+Call `query_data` with `{ operation: "describe-tables", project_id, table_names: [<user-selected tables>] }`.
+
+Review the returned schemas with the user. Note column names, data types, and any partitioning. Ask if any additional tables should be included.
+
+### Step 6 — Generate SQL Queries
+
+Using the prompt template in `templates/query-generation-prompt.md`, generate SQL queries tailored to the research objective.
+
+**Substitute:**
+- `{objective}` — the research objective from Step 3
+- `{context}` — background context from Step 3
+- `{available_tables}` — full table list from Step 4
+- `{table_definitions}` — schema details from Step 5
+
+Present all generated queries to the user. For each query, show:
+- Query ID and purpose
+- The SQL
+- Expected output columns
+
+Ask: **"Do these queries look correct? Which ones should we run, and are there any you'd like to modify?"**
+
+Allow the user to edit, add, or remove queries before execution.
+
+### Step 7 — Execute Approved Queries
+
+For each approved query, call `query_data` with `{ operation: "execute-query", project_id, query: "<sql>" }`.
+
+Execute one query at a time. After each:
+- Show the result rows
+- Ask: "Does this look as expected, or should we investigate further before continuing?"
+
+If a query returns no results: note this explicitly and ask if the query should be revised.
+If a query errors: show the error and ask the user how to proceed.
+
+### Step 8 — Synthesize Findings
+
+Using the prompt template in `templates/synthesis-prompt.md`, synthesize all query results into a ResearchFindings.md report.
+
+**Substitute:**
+- `{objective}` — the research objective
+- `{context}` — background context
+- `{query_results}` — all query results (as structured data)
+- `{table_definitions}` — the schema reference from Step 5
+
+Present the full ResearchFindings.md to the user. Ask: **"Does this accurately capture the findings? Any corrections or additions?"**
+
+Incorporate feedback.
+
+### Step 9 — Persist Findings
+
+Call `update_memory`:
+```
+memory_type: "research_finding"
+title: "ResearchFindings — <objective summary> — <YYYY-MM-DD>"
+content: {
+  text: "<full ResearchFindings.md markdown>",
+  objective: "<objective>",
+  tables_used: ["<table1>", "<table2>"],
+  queries_run: <count>
+}
+tags: ["research", "<domain-tag>", "<date-tag>"]
+source_role: "researcher"
+```
+
+### Step 10 — Summarize
+
+Tell the user:
+- Project ID and memory ID of the persisted finding
+- Tables queried and query count
+- Key findings (2–3 sentence summary)
+- How developers can access this finding: `fetch_context` with `{ project_id, memory_type: "research_finding" }`
+
+---
+
+## Error Handling
+
+- If `list-tables` returns empty: Athena credentials may not be configured. Inform the user and check the server configuration.
+- If a query exceeds the 100KB result cap: the tool returns a truncation notice. Acknowledge this in the findings methodology section.
+- If the user asks to run a non-SELECT query: refuse and explain the SELECT-only constraint. Offer an alternative SELECT formulation if possible.
+- If synthesis produces speculative conclusions: flag them explicitly with confidence levels (High/Medium/Low) per the synthesis template.

package/skills/research-analyze/templates/query-generation-prompt.md

@@ -0,0 +1,61 @@
+# Prompt Template: Generate SQL Queries
+
+When this template is used, substitute all `{placeholders}` with actual values, then generate the queries as instructed.
+
+---
+
+You are a senior data analyst expert in SQL and data warehousing. Using the research objective and schema information below, generate SQL queries that will answer the research questions effectively.
+
+## Research Objective
+
+{objective}
+
+## Research Context
+
+{context}
+
+## Available Schema
+
+**Tables discovered:**
+{available_tables}
+
+**Table definitions:**
+{table_definitions}
+
+## Instructions
+
+Generate a set of SQL queries that address the research objective. Organise them from exploratory (broad counts, distributions) to specific (targeted metrics that directly answer the objective).
+
+For EACH query provide:
+
+### Query: {query-id} — {short title}
+
+**Purpose:** one sentence describing what this query answers
+
+**SQL:**
+```sql
+-- {explanation of non-obvious logic}
+SELECT
+  ...
+FROM {table}
+WHERE ...
+  AND date_partition BETWEEN '{{start_date}}' AND '{{end_date}}'
+LIMIT 1000
+```
+
+**Expected output columns:**
+| Column | Type | Description |
+|--------|------|-------------|
+| ... | ... | ... |
+
+**Notes:** caveats, known data quality issues, or follow-up queries suggested
+
+---
+
+**Query writing conventions:**
+- Use standard ANSI SQL where possible
+- Add comments inside SQL explaining non-obvious logic
+- Parameterise date ranges using placeholders like `{{start_date}}` and `{{end_date}}`
+- Include `LIMIT` clauses on exploratory queries
+- For Athena: use partition columns in WHERE clauses to control cost
+- Only SELECT statements — no DDL or DML

package/skills/research-analyze/templates/synthesis-prompt.md

@@ -0,0 +1,67 @@
+# Prompt Template: Synthesize Research Findings
+
+When this template is used, substitute all `{placeholders}` with actual values, then generate the findings report as instructed.
+
+---
+
+You are a senior data scientist and technical writer. Using the research objective, context, and query results below, synthesise a clear and actionable research findings report.
+
+## Research Objective
+
+{objective}
+
+## Research Context
+
+{context}
+
+## Query Results
+
+{query_results}
+
+## Available Schema Reference
+
+{table_definitions}
+
+## Instructions
+
+Produce a research findings report titled `# ResearchFindings.md` with the following sections:
+
+### 1. Executive Summary
+2–4 sentences: the most important finding and its business implication.
+
+### 2. Methodology
+Describe:
+- Data sources used (tables, date ranges)
+- Queries run and what each was designed to measure
+- Data quality considerations or limitations discovered
+
+### 3. Key Findings
+For each significant finding:
+
+**Finding N: {descriptive title}**
+- **Evidence:** specific numbers, percentages, or trends from the query results
+- **Interpretation:** what this means in business or research terms
+- **Confidence:** High / Medium / Low — with reasoning
+
+### 4. Trends and Patterns
+Describe temporal trends, correlations, anomalies, or unexpected patterns observed across the query results.
+
+### 5. Limitations and Caveats
+Be explicit about:
+- Data gaps or missing periods
+- Potential biases in the data
+- Queries that returned no results and what that implies
+- Assumptions made during the analysis
+
+### 6. Recommendations
+Actionable next steps based on the findings. Each recommendation must state:
+- **Action:** what to do
+- **Owner:** who should act on it
+- **Rationale:** why this follows from the data
+
+### 7. Follow-up Research Questions
+List 3–5 questions this analysis surfaced but could not answer, to guide future research sessions.
+
+---
+
+Format as a structured Markdown document suitable for sharing with stakeholders.

package/skills/shared/codifier-tools.md

@@ -0,0 +1,123 @@
+# Codifier MCP Tools Reference
+
+This document describes all 5 MCP tools exposed by the Codifier server. Reference this when executing any Codifier skill.
+
+---
+
+## 1. `fetch_context`
+
+Retrieve memories from the shared knowledge base, filtered by project, type, tags, or full-text search.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | string (UUID) | ✓ | Project to scope the query to |
+| `memory_type` | enum | — | Filter by type: `rule`, `document`, `api_contract`, `learning`, `research_finding` |
+| `tags` | string[] | — | All supplied tags must be present on the memory |
+| `query` | string | — | Full-text search applied to title and content |
+| `limit` | number (1–100) | — | Max results (default: 20) |
+
+**Returns:** Array of memory records with `id`, `title`, `content`, `memory_type`, `tags`, `source_role`, `created_at`.
+
+**Usage patterns:**
+- Fetch all rules for a project: `{ project_id, memory_type: "rule" }`
+- Fetch researcher findings relevant to auth: `{ project_id, memory_type: "research_finding", tags: ["auth"] }`
+- Full-text search across all memory types: `{ project_id, query: "payment processing" }`
+
+---
+
+## 2. `update_memory`
+
+Create a new memory or update an existing one in the shared knowledge base.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | string (UUID) | ✓ | Project to scope this memory to |
+| `memory_type` | enum | ✓ | `rule`, `document`, `api_contract`, `learning`, `research_finding` |
+| `title` | string | ✓ | Short descriptive title |
+| `content` | object | ✓ | Structured content payload (any JSON object) |
+| `id` | string (UUID) | — | If provided, updates the existing record instead of creating |
+| `tags` | string[] | — | Tags for filtering and categorization |
+| `category` | string | — | Category grouping (e.g., "security", "error-handling") |
+| `description` | string | — | Human-readable summary |
+| `confidence` | number (0–1) | — | Confidence score (default: 1.0) |
+| `source_role` | string | — | Role that produced this memory (e.g., "developer", "researcher") |
+
+**Returns:** The created or updated memory record including its `id`.
+
+**Usage patterns:**
+- Store a generated Rules.md: `{ project_id, memory_type: "document", title: "Rules.md", content: { text: "..." }, source_role: "developer" }`
+- Store a research finding: `{ project_id, memory_type: "research_finding", title: "Q4 Retention Analysis", content: { summary: "...", findings: [...] }, source_role: "researcher" }`
+- Update an existing memory: `{ project_id, id: "<existing-id>", memory_type: "rule", title: "...", content: {...} }`
+
+---
+
+## 3. `manage_projects`
+
+Create, list, or switch the active project.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `operation` | enum | ✓ | `create`, `list`, or `switch` |
+| `name` | string | For `create` | Project name |
+| `org` | string | — | Organisation name (optional for `create`) |
+| `project_id` | string (UUID) | For `switch` | Project to switch to |
+
+**Returns:**
+- `list`: Array of projects with `id`, `name`, `org`, `created_at`
+- `create`: The created project record including its `id`
+- `switch`: Confirmation of the active project
+
+**Usage patterns:**
+- List all projects: `{ operation: "list" }`
+- Create a new project: `{ operation: "create", name: "Payments Redesign", org: "Acme Corp" }`
+- Switch to an existing project: `{ operation: "switch", project_id: "<uuid>" }`
+
+---
+
+## 4. `pack_repo`
+
+Condense a code repository into a versioned text snapshot using RepoMix. The snapshot is stored in the `repositories` table and can be retrieved for context.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `url` | string | ✓ | Repository URL (e.g., `https://github.com/org/repo`) or local path |
+| `project_id` | string (UUID) | ✓ | Project to associate the snapshot with |
+| `version_label` | string | — | Version label for this snapshot (e.g., `"v1.2.3"`, `"sprint-5"`, `"2026-02"`) |
+
+**Returns:** Repository record with `id`, `url`, `version_label`, `token_count`, `file_count`, and `created_at`.
+
+**Usage patterns:**
+- Pack a public GitHub repo: `{ url: "https://github.com/org/repo", project_id, version_label: "2026-02" }`
+- Pack multiple repos for brownfield onboarding: call once per repo URL
+
+**Note:** Large repos may take 30–60 seconds. The packed snapshot is plain text suitable for LLM context.
+
+---
+
+## 5. `query_data`
+
+Discover schemas and execute SELECT queries against an AWS Athena data warehouse.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `operation` | enum | ✓ | `list-tables`, `describe-tables`, or `execute-query` |
+| `project_id` | string (UUID) | ✓ | Project UUID for session scoping |
+| `query` | string | For `execute-query` | SQL SELECT statement to execute |
+| `table_names` | string[] | For `describe-tables` | Tables to describe |
+
+**Returns:**
+- `list-tables`: Array of available table names
+- `describe-tables`: Schema definitions for requested tables
+- `execute-query`: Query results (capped at 100KB; truncation notice included if limit hit)
+
+**Usage patterns:**
+- Discover available tables: `{ operation: "list-tables", project_id }`
+- Get schema for selected tables: `{ operation: "describe-tables", project_id, table_names: ["events", "users"] }`
+- Execute a query: `{ operation: "execute-query", project_id, query: "SELECT user_id, COUNT(*) FROM events GROUP BY 1 LIMIT 100" }`
+
+**Constraints:** Only SELECT statements are permitted. DDL and DML are rejected.