@crewpilot/agent 1.0.0

package/prompts/skills/insights-knowledge-base/SKILL.md

@@ -0,0 +1,181 @@
+# Knowledge Base
+
+> **Pillar**: Insights | **ID**: `insights-knowledge-base`
+
+## Purpose
+
+Persistent cross-session memory system. Stores decisions, patterns, lessons learned, and context so the team's knowledge compounds over time instead of resetting every conversation.
+
+## Activation Triggers
+
+- "remember this", "recall", "what did we decide about"
+- "history", "past decisions", "context from last time"
+- "save this insight", "knowledge base"
+- Implicitly used by other skills to check for prior context
+
+## Methodology
+
+### Process Flow
+
+```dot
+digraph knowledge_base {
+    rankdir=TB;
+    node [shape=box];
+
+    subgraph cluster_store {
+        label="Store Operations";
+        decision [label="Store Decision"];
+        lesson [label="Store Lesson"];
+        pattern [label="Store Pattern"];
+    }
+
+    subgraph cluster_retrieve {
+        label="Retrieve Operations";
+        query [label="Direct Query"];
+        contextual [label="Contextual Retrieval\n(by other skills)"];
+        timeline [label="Timeline View"];
+    }
+
+    subgraph cluster_maintain {
+        label="Maintenance";
+        consolidate [label="Pattern Consolidation"];
+        export [label="Knowledge Export", shape=doublecircle];
+    }
+
+    decision -> query [style=dotted];
+    lesson -> query [style=dotted];
+    pattern -> query [style=dotted];
+    contextual -> consolidate [style=dotted, label="periodic"];
+    consolidate -> export;
+}
+```
+
+### Store Operations
+
+#### Store a Decision
+When a significant decision is made during any skill:
+1. Extract: decision, rationale, alternatives rejected, date, related files
+2. Tag with categories: `architecture`, `technology`, `process`, `convention`
+3. Store via `catalyst_knowledge_store`
+
+Entry format:
+```json
+{
+  "type": "decision",
+  "title": "{short title}",
+  "content": "{decision and rationale}",
+  "tags": ["{category}", "{technology}"],
+  "related_files": ["{paths}"],
+  "timestamp": "{ISO date}"
+}
+```
+
+#### Store a Lesson Learned
+When debugging reveals a non-obvious insight:
+1. Extract: what happened, why, prevention measure
+2. Tag with: `bug`, `performance`, `security`, `gotcha`
+3. Link to the fix commit if available
+
+#### Store a Pattern
+When `pattern-detection` identifies a codebase convention:
+1. Document the pattern with a code example
+2. Tag with: `pattern`, `convention`, `style`
+3. Reference canonical implementation files
+
+### Retrieve Operations
+
+#### Direct Query
+User asks "what did we decide about X":
+1. Search knowledge base via `catalyst_knowledge_search`
+2. Return matching entries with context
+3. If multiple matches, rank by relevance and recency
+
+#### Contextual Retrieval (by other skills)
+Skills query the knowledge base before starting:
+1. `solution-design` checks for prior decisions on the same topic
+2. `architecture-planner` retrieves existing ADRs
+3. `root-cause-analysis` checks if similar bugs were solved before
+4. `code-quality` retrieves documented conventions
+
+#### Timeline View
+User asks "what happened this week/sprint":
+1. Retrieve entries within the time range via `catalyst_knowledge_timeline`
+2. Group by type (decisions, lessons, patterns)
+3. Present as a chronological narrative
+
+### Maintenance Operations
+
+#### Pattern Consolidation
+Periodically:
+1. Identify related entries that can be merged
+2. Archive stale entries (decisions reversed, patterns abandoned)
+3. Flag contradictory entries for resolution
+
+#### Knowledge Export
+Generate a summary document:
+1. Active decisions and their current status
+2. Team conventions with code examples
+3. Common gotchas and their solutions
+
+## Tools Required
+
+- `catalyst_knowledge_store` — Write entries to the knowledge base
+- `catalyst_knowledge_search` — Full-text search across entries
+- `catalyst_knowledge_timeline` — Time-range queries
+- `catalyst_knowledge_patterns` — Pattern frequency analysis
+- `catalyst_knowledge_export` — Generate summary documents
+
+## Output Format
+
+### For Storage
+```
+## [Catalyst → Knowledge Base: Stored]
+
+✓ Stored: {type} — "{title}"
+Tags: {tags}
+Related: {files}
+```
+
+### For Retrieval
+```
+## [Catalyst → Knowledge Base: Retrieved]
+
+### Results for "{query}"
+Found {N} entries:
+
+#### {title} ({type}, {date})
+{content}
+**Tags**: {tags}
+**Related files**: {paths}
+
+---
+(repeat per entry)
+```
+
+### For Timeline
+```
+## [Catalyst → Knowledge Base: Timeline]
+
+### {date range}
+
+**Decisions**
+- {title}: {summary}
+
+**Lessons Learned**
+- {title}: {summary}
+
+**Patterns**
+- {title}: {summary}
+```
+
+## Chains To
+
+- Any skill can chain TO knowledge-base to store findings
+- Knowledge-base is queried BY other skills, but doesn't chain outward
+
+## Anti-Patterns
+
+- Do NOT store trivial information — only decisions, lessons, and patterns
+- Do NOT store ephemeral state (what files are open, current branch)
+- Do NOT return raw database entries — synthesize into readable summaries
+- Do NOT store sensitive data (credentials, tokens, personal info)

package/prompts/skills/insights-pattern-detection/SKILL.md

@@ -0,0 +1,142 @@
+# Pattern Detection
+
+> **Pillar**: Insights | **ID**: `insights-pattern-detection`
+
+## Purpose
+
+Codebase-wide pattern mining and anti-pattern identification. Analyzes structural health, detects recurring issues, tracks technical debt, and identifies emerging trends across the project.
+
+## Activation Triggers
+
+- "codebase health", "find patterns", "anti-patterns", "tech debt"
+- "what patterns are we using", "code trends", "structural analysis"
+- Automatically triggered when `root-cause-analysis` finds a systemic issue
+
+## Methodology
+
+### Process Flow
+
+```dot
+digraph pattern_detection {
+    rankdir=TB;
+    node [shape=box];
+
+    structure [label="Phase 1\nStructure Scan"];
+    mining [label="Phase 2\nPattern Mining"];
+    antipattern [label="Phase 3\nAnti-Pattern Detection"];
+    debt [label="Phase 4\nTechnical Debt Inventory"];
+    trends [label="Phase 5\nTrend Analysis", shape=diamond];
+    report [label="Report", shape=doublecircle];
+
+    structure -> mining;
+    mining -> antipattern;
+    antipattern -> debt;
+    debt -> trends;
+    trends -> report [label="historical\ndata available"];
+    debt -> report [label="no historical data"];
+}
+```
+
+### Phase 1 — Structure Scan
+1. Map the project structure: directories, modules, layers
+2. Identify architectural patterns in use:
+   - MVC, MVVM, Clean Architecture, Hexagonal
+   - Microservices vs. monolith vs. modular monolith
+   - API patterns: REST, GraphQL, RPC
+3. Detect organizational patterns: feature-based vs. layer-based vs. hybrid
+
+### Phase 2 — Pattern Mining
+Scan for recurring code patterns:
+
+| Category | Patterns to Detect |
+|---|---|
+| **Error handling** | Try-catch styles, error propagation, error types |
+| **Data access** | ORM patterns, raw queries, repository pattern |
+| **State management** | Global state, dependency injection, singletons |
+| **API design** | Route organization, middleware chains, validation |
+| **Testing** | Test structure, mock strategies, fixture patterns |
+| **Configuration** | Env vars, config objects, feature flags |
+
+For each pattern found:
+- **Frequency**: How often it appears
+- **Consistency**: Are there deviations from the pattern?
+- **Quality**: Is this a good pattern for this context?
+
+### Phase 3 — Anti-Pattern Detection
+Flag known anti-patterns:
+
+| Anti-Pattern | Symptoms |
+|---|---|
+| **God Object/File** | Single file > 500 lines with mixed responsibilities |
+| **Circular Dependencies** | Module A imports B imports A |
+| **Shotgun Surgery** | Small change requires touching 5+ files |
+| **Feature Envy** | Function uses more of another module's data than its own |
+| **Dead Code** | Unreachable functions, unused exports |
+| **Copy-Paste** | Near-duplicate code blocks across files |
+| **Primitive Obsession** | Strings/numbers used where domain types belong |
+| **Configuration Drift** | Same setting configured differently in multiple places |
+
+### Phase 4 — Technical Debt Inventory
+For each anti-pattern or inconsistency:
+1. Estimate effort to fix (T-shirt size)
+2. Assess impact on team velocity
+3. Rate urgency: address now vs. track vs. accept
+
+### Phase 5 — Trend Analysis
+If `catalyst_knowledge_search` has historical data:
+1. Compare current patterns vs. previous scans
+2. Identify patterns that are spreading (good or bad)
+3. Flag entropy increase — growing inconsistency over time
+
+## Tools Required
+
+- `codebase` — Full project scan
+- `terminal` — Run static analysis tools
+- `catalyst_metrics_complexity` — Complexity metrics per module
+- `catalyst_knowledge_search` — Historical pattern data
+- `catalyst_knowledge_store` — Record findings for future comparison
+
+## Output Format
+
+```
+## [Catalyst → Pattern Detection]
+
+### Architecture
+{detected patterns and organization style}
+
+### Code Patterns
+| Pattern | Category | Frequency | Consistency | Quality |
+|---|---|---|---|---|
+| {pattern} | {category} | {count} | {high/medium/low} | {good/acceptable/poor} |
+
+### Anti-Patterns
+| Anti-Pattern | Locations | Severity | Fix Effort |
+|---|---|---|---|
+| {anti-pattern} | {files/modules} | {high/med/low} | {T-shirt} |
+
+### Technical Debt
+| Item | Impact | Urgency | Effort |
+|---|---|---|---|
+| {debt item} | {velocity/quality/security} | {now/track/accept} | {T-shirt} |
+
+### Trends (if historical data available)
+{getting better / getting worse / stable}
+
+### Summary
+Codebase health: {score}/10
+Top concern: {most impactful issue}
+Quick wins: {list of low-effort improvements}
+```
+
+## Chains To
+
+- `code-quality` — Deep review of flagged anti-pattern locations
+- `architecture-planner` — Restructure if systemic issues found
+- `knowledge-base` — Store scan results for trend tracking
+
+## Anti-Patterns (meta)
+
+- Do NOT flag patterns as anti-patterns based on ideology — evaluate in context
+- Do NOT report dead code without verifying it's truly unreachable
+- Do NOT recommend rewrites for working code with manageable debt
+- Do NOT present a massive list without prioritization

package/prompts/skills/strategize-architecture-planner/SKILL.md

@@ -0,0 +1,141 @@
+# Architecture Planner
+
+> **Pillar**: Strategize | **ID**: `strategize-architecture-planner`
+
+## Purpose
+
+Transform decisions into concrete architecture plans with component diagrams, API contracts, data flow, and implementation roadmaps. Produces living design documents that evolve with the codebase.
+
+## Activation Triggers
+
+- "plan the architecture", "design the system", "create an RFC", "structure this"
+- "how should I organize", "component diagram", "data flow", "API design"
+- After `solution-design` selects an approach that needs detailing
+
+## Methodology
+
+### Process Flow
+
+```dot
+digraph architecture_planner {
+    rankdir=TB;
+    node [shape=box];
+
+    scope [label="Phase 1\nScope Definition"];
+    components [label="Phase 2\nComponent Design"];
+    dataflow [label="Phase 3\nData Flow"];
+    roadmap [label="Phase 4\nImplementation Roadmap"];
+    adr [label="Phase 5\nADR", shape=diamond, style=filled, fillcolor="#ffcccc"];
+    feature [label="feature-builder\n(Milestone M1)", shape=doublecircle];
+
+    scope -> components;
+    components -> dataflow;
+    dataflow -> roadmap;
+    roadmap -> adr;
+    adr -> feature [label="approved"];
+    adr -> components [label="user requests\nrevisions"];
+}
+```
+
+### Phase 1 — Scope Definition
+1. Identify system boundaries — what's in scope vs. out of scope
+2. List actors (users, services, external systems)
+3. Define key quality attributes: scalability, latency, availability, consistency
+4. Read existing codebase structure to understand current architecture
+
+### Phase 2 — Component Design
+1. Decompose into components/modules with clear responsibilities
+2. Define interfaces between components (API contracts, event schemas)
+3. Identify shared dependencies and data stores
+4. Map to existing code structure where applicable
+
+Output as a component table:
+
+| Component | Responsibility | Inputs | Outputs | Dependencies |
+|---|---|---|---|---|
+| | | | | |
+
+### Phase 3 — Data Flow
+1. Trace the primary user journey through the system
+2. Identify data transformations at each step
+3. Mark synchronous vs. asynchronous boundaries
+4. Identify potential bottlenecks and failure points
+
+Produce a numbered flow:
+```
+1. User → API Gateway (HTTPS)
+2. API Gateway → Auth Service (validate token)
+3. Auth Service → User DB (query)
+...
+```
+
+### Phase 4 — Implementation Roadmap
+1. Break into milestones (each independently deployable/testable)
+2. Order by dependency graph — foundations first
+3. Estimate effort per milestone (T-shirt sizes)
+4. Identify the critical path
+5. Mark "go/no-go" decision points
+
+### Phase 5 — ADR (Architecture Decision Record)
+
+<HARD-GATE>
+Do NOT begin implementation until the architecture plan (components, data flow, roadmap) has been presented to and approved by the user.
+If the user has not explicitly confirmed the architecture, do NOT proceed.
+</HARD-GATE>
+
+If `require_adr` is true in config, generate:
+
+```markdown
+# ADR-{NNN}: {Title}
+
+## Status: Proposed
+## Context: {why this decision is needed}
+## Decision: {what was decided}
+## Consequences: {positive and negative}
+## Alternatives Considered: {options rejected and why}
+```
+
+## Tools Required
+
+- `codebase` — Analyze existing project structure and dependencies
+- `terminal` — Run dependency analysis commands (package.json, imports, etc.)
+- `catalyst_knowledge_search` — Retrieve prior architecture decisions
+
+## Output Format
+
+```
+## [Catalyst → Architecture Planner]
+
+### Scope
+{boundaries, actors, quality attributes}
+
+### Components
+{component table}
+
+### Data Flow
+{numbered flow}
+
+### Implementation Roadmap
+| Milestone | Description | Effort | Dependencies |
+|---|---|---|---|
+| M1 | | | |
+
+### Critical Path
+{sequence}
+
+### ADR (if enabled)
+{ADR document}
+```
+
+## Chains To
+
+- `feature-builder` — Start implementing milestone M1
+- `test-first` — Write integration tests for component interfaces
+- `doc-governance` — Ensure architecture docs stay synchronized
+
+## Anti-Patterns
+
+- Do NOT design in a vacuum — always scan the existing codebase first
+- Do NOT create components with unclear responsibilities (god-service smell)
+- Do NOT skip the roadmap — architecture without sequencing is just a diagram
+- Do NOT ignore existing patterns — evolve, don't replace, unless explicitly asked

package/prompts/skills/strategize-solution-design/SKILL.md

@@ -0,0 +1,118 @@
+# Solution Design
+
+> **Pillar**: Strategize | **ID**: `strategize-solution-design`
+
+## Purpose
+
+Structured ideation and trade-off analysis for technical decisions. Transforms vague questions into evaluated options with clear recommendations.
+
+## Activation Triggers
+
+- "brainstorm", "explore options", "what are the approaches", "tradeoffs", "should I use X or Y"
+- Any open-ended technical question with multiple viable paths
+
+## Methodology
+
+### Process Flow
+
+```dot
+digraph solution_design {
+    rankdir=TB;
+    node [shape=box];
+
+    frame [label="Phase 1\nProblem Framing"];
+    options [label="Phase 2\nOption Generation\n(3-4 approaches)"];
+    matrix [label="Phase 3\nTrade-off Matrix"];
+    recommend [label="Phase 4\nRecommendation", shape=diamond, style=filled, fillcolor="#ffcccc"];
+    arch [label="architecture-planner", shape=doublecircle];
+    build [label="feature-builder", shape=doublecircle];
+
+    frame -> options;
+    options -> matrix;
+    matrix -> recommend;
+    recommend -> arch [label="needs detailed design"];
+    recommend -> build [label="ready to implement"];
+    recommend -> options [label="user rejects\nall options"];
+}
+```
+
+### Phase 1 — Problem Framing
+1. Restate the problem in one sentence
+2. Identify constraints: time, team size, existing tech stack, scale requirements
+3. Ask 1-2 clarifying questions ONLY if the problem is genuinely ambiguous
+
+### Phase 2 — Option Generation
+1. Generate 3-4 distinct approaches (configurable via `max_options` in config)
+2. Each option must include:
+   - **Name**: Short memorable label
+   - **Approach**: 2-3 sentence description
+   - **Strengths**: What it does well
+   - **Risks**: What could go wrong
+   - **Effort**: T-shirt size (S/M/L/XL) with justification
+3. Options must be genuinely different — not variations of the same approach
+
+### Phase 3 — Trade-off Matrix
+Build a comparison table:
+
+| Criterion | Option A | Option B | Option C |
+|---|---|---|---|
+| Implementation effort | | | |
+| Maintainability | | | |
+| Performance | | | |
+| Team familiarity | | | |
+
+Rate each cell: `++` (strong), `+` (good), `~` (neutral), `-` (weak), `--` (poor)
+
+### Phase 4 — Recommendation
+
+<HARD-GATE>
+Do NOT proceed to implementation or architecture planning until the user has reviewed the trade-off matrix and confirmed the recommended option.
+Present the recommendation and wait for explicit approval or selection.
+</HARD-GATE>
+
+1. State the recommended option clearly
+2. Provide confidence level (1-10) with reasoning
+3. Identify the "decision reversal cost" — how hard is it to switch later
+4. List 1-2 things to validate before committing
+
+## Tools Required
+
+- `codebase` — Scan existing stack for constraints
+- `fetch` — Pull external docs/benchmarks when comparing technologies
+- `catalyst_knowledge_search` — Check if similar decisions were made before
+
+## Output Format
+
+```
+## [Catalyst → Solution Design]
+
+### Problem
+{one-sentence problem statement}
+
+### Options
+1. **{Name}** — {approach}
+   - Strengths: ...
+   - Risks: ...
+   - Effort: {T-shirt}
+
+### Trade-off Matrix
+{table}
+
+### Recommendation
+**{Option Name}** (Confidence: {N}/10)
+{reasoning}
+
+**Reversal cost**: {Low/Medium/High}
+**Validate first**: {list}
+```
+
+## Chains To
+
+- `architecture-planner` — When the recommended option needs detailed design
+- `feature-builder` — When the user wants to start implementing immediately
+
+## Anti-Patterns
+
+- Do NOT generate options just to fill a quota — 2 genuine options beat 4 padded ones
+- Do NOT recommend without stating confidence and reversal cost
+- Do NOT skip the trade-off matrix — it's the core value of this skill

package/scripts/postinstall.js

@@ -0,0 +1,108 @@
+/**
+ * postinstall.js — Runs after `npm install @crewpilot/agent`
+ * 
+ * Creates .github/ files in the user's project so @Catalyst agent
+ * appears in Copilot Chat dropdown automatically.
+ * 
+ * Uses INIT_CWD (set by npm to the directory where `npm install` was run).
+ * Silently exits on global installs or npx (no project root).
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// INIT_CWD is the directory where the user ran `npm install`
+const projectRoot = process.env.INIT_CWD;
+
+// Skip if no project root (global install, npx, CI, etc.)
+if (!projectRoot) {
+  process.exit(0);
+}
+
+// Skip if installing as a dependency of this package itself (dev scenario)
+const ownPackageDir = path.join(__dirname, '..');
+if (path.resolve(projectRoot) === path.resolve(ownPackageDir)) {
+  process.exit(0);
+}
+
+// Skip if no package.json in project root (not a real project)
+if (!fs.existsSync(path.join(projectRoot, 'package.json'))) {
+  process.exit(0);
+}
+
+const githubDir = path.join(projectRoot, '.github');
+const promptsDir = path.join(__dirname, '..', 'prompts');
+
+// If prompts aren't bundled, silently exit
+if (!fs.existsSync(promptsDir)) {
+  process.exit(0);
+}
+
+let created = 0;
+let skipped = 0;
+
+/**
+ * Copy a file from prompts/ to .github/ — never overwrites existing files
+ */
+function syncFile(srcName, destRelative) {
+  const src = path.join(promptsDir, srcName);
+  const dest = path.join(githubDir, destRelative);
+
+  if (!fs.existsSync(src)) return;
+
+  if (fs.existsSync(dest)) {
+    skipped++;
+    return;
+  }
+
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+  created++;
+}
+
+/**
+ * Copy all skills from prompts/skills/ to .github/skills/
+ */
+function syncSkills() {
+  const skillsDir = path.join(promptsDir, 'skills');
+  if (!fs.existsSync(skillsDir)) return;
+
+  const skillDirs = fs.readdirSync(skillsDir).filter(d =>
+    fs.statSync(path.join(skillsDir, d)).isDirectory()
+  );
+
+  for (const name of skillDirs) {
+    const src = path.join(skillsDir, name, 'SKILL.md');
+    if (!fs.existsSync(src)) continue;
+
+    const dest = path.join(githubDir, 'skills', name, 'SKILL.md');
+    if (fs.existsSync(dest)) {
+      skipped++;
+      continue;
+    }
+
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(src, dest);
+    created++;
+  }
+}
+
+// --- Run ---
+try {
+  fs.mkdirSync(githubDir, { recursive: true });
+
+  syncFile('agent.md', path.join('agents', 'catalyst.md'));
+  syncFile('copilot-instructions.md', 'copilot-instructions.md');
+  syncFile('catalyst.config.json', 'catalyst.config.json');
+  syncSkills();
+
+  if (created > 0) {
+    console.log(`\n  ⚡ CrewPilot: Created ${created} file(s) in .github/ (${skipped} already existed)`);
+    console.log('  ⚡ Open Copilot Chat and select @Catalyst from the agent dropdown\n');
+  }
+} catch {
+  // Silently fail — postinstall should never break npm install
+}