codifier 2.1.0

package/skills/brownfield-onboard/SKILL.md

@@ -0,0 +1,142 @@
+# Skill: Brownfield Onboard
+
+**Role:** Developer
+**Purpose:** Onboard existing codebases into the Codifier shared knowledge base by packing repositories, generating architectural summaries, and persisting learnings.
+
+See `../shared/codifier-tools.md` for full MCP tool reference.
+
+---
+
+## Prerequisites
+
+- Active MCP connection to the Codifier server
+- At least one repository URL (GitHub, GitLab, or local path)
+- A project to associate the snapshots with (existing or new)
+
+---
+
+## 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 repositories be associated with, or should we create a new one?"**
+
+- If **existing**: use the selected `project_id`.
+- If **new**: collect name and optionally org, then call `manage_projects` with `operation: "create"`.
+
+### Step 2 — Collect Repository URLs
+
+Ask the user to provide all repository URLs to onboard. They may provide:
+- One or more GitHub/GitLab/Bitbucket HTTPS URLs
+- Local filesystem paths (absolute)
+
+Ask: **"Are there any other repos to include, or is this the complete list?"**
+
+Also ask: **"What is the current state of these repos — active development, legacy, recently archived?"**
+
+### Step 3 — Fetch Existing Context
+
+Call `fetch_context` with `{ project_id }` to retrieve any prior memories for this project. Summarize relevant findings to the user — prior architectural decisions, existing rules, or previous onboarding notes are important context.
+
+### Step 3b — Surface Local Learnings
+
+Attempt to read `docs/MEMORY.md`. If the file does not exist, skip this step silently and continue to Step 4.
+
+If the file exists, scan for entries relevant to the repositories being onboarded — particularly `architecture`, `gotcha`, and `convention` categories. Present relevant local learnings to the user alongside KB context from Step 3.
+
+Note: This is a local file read — no MCP call required.
+
+### Step 4 — Pack Repositories
+
+For each repository URL:
+1. Call `pack_repo` with the URL, `project_id`, and a `version_label` (use current date: `"YYYY-MM"` or a tag like `"initial-onboard"`)
+2. Note the returned `repository_id`, `token_count`, and `file_count`
+3. Inform the user: "Packed `<repo-url>` — `<N>` files, `<M>` tokens"
+
+If a pack fails, log the error and continue with remaining repos.
+
+### Step 5 — Generate Architectural Summary
+
+Using the packed repository content (available in your context from the pack results) and any prior memories, generate a comprehensive architectural summary covering:
+
+1. **System Overview** — what the system does, its primary users, and its business purpose
+2. **Technology Stack** — languages, frameworks, databases, infrastructure
+3. **Module Structure** — major directories/packages and their responsibilities
+4. **Key Interfaces** — APIs, event buses, shared contracts between components
+5. **Data Flow** — how data moves through the system from input to output
+6. **External Dependencies** — third-party services, APIs, or systems integrated with
+7. **Known Issues / Technical Debt** — observations from the code (if apparent)
+8. **Conventions Observed** — naming patterns, file organisation, testing approach
+
+Present the summary to the user and ask: **"Does this accurately describe the system? What should be added or corrected?"**
+
+Incorporate feedback.
+
+### Step 6 — Write Local Copies
+
+Write the confirmed architectural summary as a local file in the `docs/` directory at the project root. Create the directory if it does not exist.
+
+| Artifact | Local Path |
+|----------|-----------|
+| Architectural Summary | `docs/architecture.md` |
+
+**Important:**
+- If `docs/architecture.md` already exists, ask the user before overwriting
+- If the write fails, inform the user but continue — remote persistence in the next step will still capture the artifact
+
+Inform the user: "Local copy saved to docs/architecture.md"
+
+### Step 7 — Persist Architectural Summary Remotely
+
+Call `update_memory`:
+```
+memory_type: "learning"
+title: "Architectural Summary — <repo-name or project-name>"
+content: { text: "<full summary markdown>", repos: ["<url1>", "<url2>"] }
+tags: ["architecture", "onboarding", "brownfield"]
+source_role: "developer"
+```
+
+### Step 8 — Persist Architectural Decisions
+
+For any significant architectural decisions uncovered (e.g., "uses event sourcing", "monorepo with Turborepo", "Postgres as primary store"), ask the user which to persist as formal documents.
+
+For each confirmed decision:
+1. Write a local copy to `docs/adr-<kebab-slug>.md` (convert the decision title to lowercase kebab-case, e.g., "Uses Event Sourcing" → `docs/adr-uses-event-sourcing.md`)
+2. Then call `update_memory`:
+```
+memory_type: "document"
+title: "ADR: <decision title>"
+content: { text: "<decision description, rationale, and consequences>" }
+tags: ["adr", "architecture"]
+source_role: "developer"
+```
+
+### Step 9 — Summarize
+
+Tell the user:
+- Project ID
+- Repositories packed (with IDs and token counts)
+- Memories persisted (IDs and titles)
+- Local copies written to `docs/` (architecture.md, any ADR files)
+- How to retrieve this context in future: `fetch_context` with `{ project_id, tags: ["architecture"] }`
+
+---
+
+## Error Handling
+
+- If `pack_repo` times out or fails: note the error in the summary, ask the user if they want to retry or skip.
+- If a repo is private and credentials are not configured: inform the user that the server needs the relevant token (`GITHUB_TOKEN`, `GITLAB_TOKEN`) configured as an environment variable.
+- If the packed content is very large (>500K tokens): focus the architectural summary on the highest-level structural observations rather than deep code analysis.
+
+---
+
+## End-of-Workflow Memory Capture
+
+After completing Step 9, suggest to the user:
+
+> "You may have learned things during this onboarding session worth capturing. Run `/remember` to capture session learnings to docs/MEMORY.md, or `/push-memory` to sync existing local memories to the shared KB."
+
+This is a suggestion only — do not automatically invoke the capture or push Skills.

package/skills/capture-session/SKILL.md

@@ -0,0 +1,111 @@
+# Skill: Capture Session
+
+**Role:** Any
+**Purpose:** Capture session learnings — gotchas, conventions, insights, what-to-do, what-not-to-do — into the local `docs/MEMORY.md` file for later review and optional KB sync.
+
+See `../shared/codifier-tools.md` for full MCP tool reference.
+
+---
+
+## Prerequisites
+
+- A `docs/MEMORY.md` file (created by `npx codifier init`; if missing, this skill will create it with a placeholder header)
+- Optionally an active MCP connection (only needed if the user wants to confirm the `project_id`)
+
+---
+
+## When to Use / When NOT to Use
+
+**Use this skill when:**
+- You've learned something during a session worth remembering — a debugging insight, an API behavior, a convention, a gotcha, or a team decision
+- You are at the end of any Codifier workflow and want to capture what you learned along the way
+
+**Do NOT use this skill when:**
+- You want to persist structured project artifacts such as rules, requirements, or architecture docs — use `/codify`, `/onboard`, or `/research` instead
+- You want to push memories to the shared KB for the team to access — use `/push-memory` instead
+
+---
+
+## Workflow
+
+Follow these steps conversationally. You are the state machine — write to the local file only; do not call `update_memory` during this skill.
+
+### Step 1 — Confirm Project Context
+
+Read `docs/MEMORY.md`.
+
+- If the file **exists**: extract the project name and ID from the header and present them to the user for confirmation.
+- If the file **does not exist**: create it with the following placeholder header, substituting today's date for `<today's date>`:
+
+```markdown
+# Project Memory
+_Last updated: <today's date>_
+
+```
+
+Ask the user: **"What project are these learnings for?"** to confirm or set the project context. Update the header with the confirmed project name if it is not already present.
+
+### Step 2 — Elicit Learnings
+
+Ask the user:
+
+**"What did you learn during this session? Think about: gotchas, surprises, conventions you discovered, things to do or avoid, insights about the codebase or tools."**
+
+Let the user respond in any format — bullet points, paragraphs, or freeform prose. Collect everything before structuring. Do not interrupt to ask for clarification mid-response; wait until the user has finished providing input.
+
+### Step 3 — Structure and Dedup
+
+For each learning the user provided:
+
+1. Assign a category from the following list, or ask the user if the right category is unclear:
+   - `architecture` — structural decisions, component relationships, design patterns
+   - `gotcha` — surprising behaviors, footguns, things that went wrong
+   - `convention` — naming, formatting, file organisation, team norms
+   - `tooling` — build tools, CLIs, libraries, dev environment
+   - `data` — schema details, query behaviors, data quirks
+   - `process` — workflow, review conventions, deployment steps
+2. Distill the learning into a concise, actionable bullet point (one line)
+3. Check for exact string matches against existing bullet points already in `docs/MEMORY.md` — skip any entry whose text is identical to an existing entry
+
+Present the structured candidates to the user grouped by category. For example:
+
+```
+**gotcha**
+- Supabase RLS blocks inserts when no matching policy exists; always test with service role key first
+
+**convention**
+- Use kebab-case for all slug fields; snake_case is reserved for database column names
+```
+
+Ask: **"Here are the learnings I've structured. Any to add, remove, or recategorize?"**
+
+Incorporate the user's feedback before proceeding.
+
+### Step 4 — Append to Local File
+
+Append the confirmed learnings to `docs/MEMORY.md`:
+
+- For each category with new entries, find the matching `## <Category>` heading in the file.
+  - If the heading already exists: append new bullet points beneath it.
+  - If the heading does not exist yet: create it at the end of the file.
+- Update the `_Last updated_` date in the header to today's date.
+
+Do NOT call `update_memory`. This step writes only to the local `docs/MEMORY.md` file.
+
+### Step 5 — Next Steps
+
+Inform the user:
+
+- "Learnings saved to docs/MEMORY.md"
+- "You can edit the file directly to refine, recategorize, or remove entries"
+- "When ready to share with your team, run /push-memory to sync to the shared KB"
+
+---
+
+## Error Handling
+
+- If `docs/MEMORY.md` **cannot be written** (e.g., permission error): present the full structured learnings as a fenced Markdown code block the user can copy-paste into the file manually.
+- If the user **provides no learnings**: ask 2–3 targeted questions to help surface implicit learnings. Example prompts:
+  - "What was the hardest part of what you worked on today?"
+  - "Did anything behave differently than you expected?"
+  - "Is there anything you'd tell a teammate before they touched this area of the code?"

package/skills/initialize-project/SKILL.md

@@ -0,0 +1,185 @@
+# Skill: Initialize Project
+
+**Role:** Developer
+**Purpose:** Set up a new project in the Codifier shared knowledge base — collecting context, optionally packing repositories, and generating four key artifacts: Rules.md, Evals.md, Requirements.md, and Roadmap.md.
+
+See `../shared/codifier-tools.md` for full MCP tool reference.
+
+---
+
+## Prerequisites
+
+- Active MCP connection to the Codifier server
+- Project context: name, description, and optionally a Scope of Work (SOW) document and repo URLs
+
+---
+
+## Workflow
+
+Follow these steps conversationally. You are the state machine — call MCP tools only for data operations.
+
+### Step 1 — Identify or Create the Project
+
+Call `manage_projects` with `operation: "list"` to show the user their existing projects.
+
+Ask: **"Is this a new project, or do you want to use an existing one?"**
+
+- If **existing**: ask the user to select from the list; use that `project_id` for all subsequent calls.
+- If **new**: collect a project name and optionally an org name, then call `manage_projects` with `operation: "create"`. Use the returned `project_id` for all subsequent calls.
+
+### Step 2 — Collect Project Context
+
+Gather the following from the user in a single conversational turn:
+
+1. **Project name** (if not already set)
+2. **Description** — what does this project build and for whom?
+3. **Scope of Work (SOW)** — paste the SOW document, or describe key deliverables if no formal SOW exists
+4. **Repository URLs** (optional) — GitHub/GitLab URLs of codebases relevant to this project
+5. **Additional context** — any constraints, tech stack, team conventions, or prior decisions
+
+Confirm you have understood all provided context before proceeding.
+
+### Step 3 — Pack Repositories (if URLs provided)
+
+For each repository URL provided:
+1. Call `pack_repo` with the URL, `project_id`, and a `version_label` (use the current date or sprint label, e.g., `"2026-02"`)
+2. Note the returned `repository_id` and `token_count`
+3. Inform the user: "Packed `<repo-url>` — `<N>` tokens"
+
+If no URLs were provided, skip this step.
+
+### Step 4 — Fetch Existing Context
+
+Call `fetch_context` with `{ project_id }` (no type filter) to retrieve any prior memories for this project. This surfaces research findings, prior rules, or existing docs that should inform the new artifacts.
+
+Summarize any relevant findings to the user before generating artifacts.
+
+### Step 4b — Surface Local Learnings
+
+Attempt to read `docs/MEMORY.md`. If the file does not exist, skip this step silently and continue to Step 5.
+
+If the file exists, scan it for entries relevant to this project — particularly entries in the `architecture`, `gotcha`, and `convention` categories. Summarize relevant local learnings to the user alongside the KB context from Step 4.
+
+Note: This is a local file read — no MCP call required.
+
+### Step 5 — Generate Rules.md
+
+Using the prompt template in `templates/rules-prompt.md`, generate a comprehensive set of development rules and coding standards for this project.
+
+**Substitute these placeholders with actual values:**
+- `{project_name}` — the project name
+- `{description}` — the project description
+- `{sow}` — the SOW or deliverables description
+- `{repo_urls}` — list of repo URLs (or "none provided")
+- `{additional_context}` — any extra context, including relevant memories from Step 4
+
+Present the generated Rules.md to the user inline. Ask: **"Does this look right? Any rules to add, remove, or change?"**
+
+Incorporate feedback before proceeding.
+
+### Step 6 — Generate Evals.md
+
+Using the prompt template in `templates/evals-prompt.md`, generate evaluation criteria from the confirmed Rules.md.
+
+**Substitute:**
+- `{rules}` — the confirmed Rules.md content
+- `{project_name}` — the project name
+- `{description}` — the project description
+
+Present Evals.md inline and ask for confirmation.
+
+### Step 7 — Generate Requirements.md
+
+Using the prompt template in `templates/requirements-prompt.md`, generate a detailed requirements document.
+
+**Substitute:**
+- `{project_name}`, `{description}`, `{sow}`, `{repo_urls}`, `{additional_context}`
+
+Present Requirements.md inline and ask for confirmation.
+
+### Step 8 — Generate Roadmap.md
+
+Using the prompt template in `templates/roadmap-prompt.md`, generate a phased implementation roadmap from Requirements.md.
+
+**Substitute:**
+- `{requirements}` — the confirmed Requirements.md content
+- `{project_name}`, `{description}`, `{repo_urls}`
+
+Present Roadmap.md inline and ask for confirmation.
+
+### Step 9 — Write Local Copies
+
+Write each confirmed artifact as a local file in the `docs/` directory at the project root. Create the directory if it does not exist.
+
+| Artifact | Local Path |
+|----------|-----------|
+| Rules | `docs/rules.md` |
+| Evals | `docs/evals.yaml` |
+| Requirements | `docs/requirements.md` |
+| Roadmap | `docs/roadmap.md` |
+
+Write each file with the confirmed artifact content (the same content that will be passed to `update_memory` in the next step).
+
+**Important:**
+- Use YAML format for Evals (the evals-prompt template produces YAML output)
+- Use Markdown for all other artifacts
+- If `docs/` already contains files with the same names, ask the user before overwriting
+- If a write fails, inform the user but continue — remote persistence in the next step will still capture the artifact
+
+Inform the user: "Local copies saved to docs/"
+
+### Step 10 — Persist All Artifacts Remotely
+
+Call `update_memory` four times — once per artifact:
+
+| Artifact | `memory_type` | `title` | `source_role` |
+|----------|--------------|---------|---------------|
+| Rules.md | `document` | `"Rules.md — <project_name>"` | `"developer"` |
+| Evals.md | `document` | `"Evals.md — <project_name>"` | `"developer"` |
+| Requirements.md | `document` | `"Requirements.md — <project_name>"` | `"developer"` |
+| Roadmap.md | `document` | `"Roadmap.md — <project_name>"` | `"developer"` |
+
+For each call, set `content: { text: "<full artifact markdown>" }` and add relevant `tags` (e.g., `["rules", "standards"]` for Rules.md).
+
+### Step 11 — Summarize
+
+Tell the user:
+- Project ID (so they can reference it later)
+- Which artifacts were generated and persisted
+- Local copies written to `docs/` (rules.md, evals.yaml, requirements.md, roadmap.md)
+- How many MCP tool calls were made total
+- How to retrieve context in future sessions: `fetch_context` with `{ project_id, memory_type: "document" }`
+
+---
+
+## Context Assembly by Scenario
+
+### Greenfield + SOW
+Emphasize SOW deliverables and functional requirements in rules and requirements generation. The roadmap should sequence SOW milestones explicitly.
+
+### Greenfield — No SOW
+Prompt the user for key deliverables and target users before generating. Rules should be general-purpose but tailored to the tech stack described.
+
+### Brownfield + SOW
+Pack all repos first (Step 3). Fetch existing memories (Step 4) — prior rules and learnings are especially important. SOW delta (what's changing vs. what exists) should drive Requirements.md.
+
+### Brownfield — No SOW
+Pack all repos first. Spend extra time in conversation understanding the existing system before generating rules — ask about pain points, constraints, and what must not change.
+
+---
+
+## Error Handling
+
+- If `pack_repo` fails for a URL: log the error, inform the user, and continue with remaining URLs.
+- If `update_memory` fails: retry once. If still failing, present the artifact as a code block the user can save manually.
+- If the user provides no description or SOW: ask at least 3 clarifying questions before attempting artifact generation.
+
+---
+
+## End-of-Workflow Memory Capture
+
+After completing Step 11, suggest to the user:
+
+> "You may have learned things during this session worth capturing. Run `/remember` to capture session learnings to docs/MEMORY.md, or `/push-memory` to sync existing local memories to the shared KB."
+
+This is a suggestion only — do not automatically invoke the capture or push Skills.

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.