forge-server 0.1.0

package/plugin/skills/knowledge-curation/SKILL.md

@@ -0,0 +1,393 @@
+---
+name: knowledge-curation
+description: >
+  This skill should be used when extracting, categorizing, and distributing learnings from
+  completed work. Used by the knowledge-keeper agent to manage memory across agents, CLAUDE.md
+  files, and project documentation.
+user-invocable: false
+---
+
+# Knowledge Curation Skill
+
+## Knowledge Extraction Methodology
+
+After a Forge workflow completes (or at significant phase boundaries), conduct a systematic review of all outputs to identify reusable knowledge. This is not a passive activity — it requires active analysis, pattern recognition, and editorial judgment about what is worth preserving.
+
+### Step 1: Review All Agent Outputs and Plan Documents
+
+Read every document produced during the workflow:
+
+- `docs/plans/YYYY-MM-DD-{TITLE}/vision.md` — for goals and constraints that shaped decisions.
+- `docs/plans/YYYY-MM-DD-{TITLE}/architecture.md` — for technical design decisions and patterns.
+- `docs/plans/YYYY-MM-DD-{TITLE}/test-plan.md` — for testing patterns and coverage strategies.
+- `docs/plans/YYYY-MM-DD-{TITLE}/agent-output/*.md` — for per-agent deliverables, decisions, and discovered constraints.
+- `docs/plans/YYYY-MM-DD-{TITLE}/escalations/*.md` — for blockers encountered and their resolutions.
+- Any git commit messages from the workflow for implementation-level context.
+
+Additionally, review the code changes themselves. Scan modified files for patterns that emerged during implementation — workarounds, patterns chosen, approaches rejected.
+
+### Step 2: Identify Knowledge Items
+
+Extract knowledge items in four categories:
+
+#### Gotchas Discovered
+
+A gotcha is a non-obvious behavior, limitation, or requirement that caused a problem or required a workaround. Gotchas are the highest-value knowledge items because they prevent future time waste.
+
+Characteristics of a gotcha worth recording:
+
+- It was not documented in official docs (or was buried and hard to find).
+- It cost more than 10 minutes to discover or resolve.
+- It would affect anyone working in this codebase, not just this specific feature.
+- The fix is non-obvious — knowing the problem exists is the hard part; the fix follows naturally.
+
+Examples of gotchas: SWC hoisting `require()` above dotenv initialization; Docker volume persistence causing auth failures; Drizzle requiring `db:generate` before `db:migrate`.
+
+#### Patterns Confirmed
+
+A pattern is an approach or architecture that was used successfully and should be replicated in similar situations. Patterns differ from gotchas in that they are prescriptive ("do this") rather than cautionary ("watch out for this").
+
+Characteristics of a pattern worth recording:
+
+- It was used across multiple modules or features, proving its generality.
+- It solved a recurring problem in a clean, maintainable way.
+- It differs from the "default" approach in a way that is not obvious but important.
+
+Examples of patterns: Proxy-based Drizzle mock for chainable queries; global NestJS modules for cross-cutting concerns; circuit breaker pattern for multi-provider AI gateway.
+
+#### Conventions Established
+
+A convention is a naming, formatting, or structural standard that the team has adopted (explicitly or implicitly) and should be followed for consistency.
+
+Characteristics of a convention worth recording:
+
+- It affects file naming, directory structure, variable naming, database naming, or infrastructure naming.
+- Inconsistency would cause confusion, integration issues, or maintenance burden.
+- It is not enforced by a linter or type system (if it were, it would not need to be documented — the tool would catch violations).
+
+Examples of conventions: Synapse naming table (kebab-case for K8s resources, specific ECR/Helm/namespace patterns); test naming pattern ("should [behavior] when [condition]").
+
+#### Decisions Made
+
+A decision is a one-time choice between alternatives, recorded with rationale so it is not revisited without new information. Decisions become the inputs for ADRs (Architectural Decision Records).
+
+Characteristics of a decision worth recording:
+
+- Multiple viable alternatives existed.
+- The choice has long-term consequences (hard to reverse).
+- The rationale is non-obvious — someone reviewing the codebase later would ask "why was it done this way?"
+
+Examples of decisions: choosing `postgres` over `pg` for the database driver; choosing RS256 over HS256 for JWT signing; choosing WebSocket over SSE for real-time updates.
+
+### Step 3: Categorize by Type
+
+For each identified knowledge item, assign a type:
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `technical-gotcha` | Non-obvious behavior that causes problems | SWC require() hoisting |
+| `architectural-pattern` | Proven approach for a recurring design problem | Circuit breaker for provider failover |
+| `workflow-preference` | How the user/team prefers to work | Commit after each logical phase, not every file |
+| `naming-convention` | Naming standards for consistency | Synapse naming table |
+| `infrastructure-gotcha` | Non-obvious infra/DevOps behavior | Docker VHDX corruption at 96GB |
+| `tooling-gotcha` | Non-obvious tool behavior | tsx watch breaks NestJS DI |
+| `testing-pattern` | Testing approach that works well | Proxy-based Drizzle mock |
+| `security-pattern` | Security-relevant approach | IRSA role naming and policy structure |
+| `decision` | One-time architectural choice | postgres.js over pg driver |
+
+### Step 4: Determine Audience
+
+Not all knowledge belongs in the same place. Determine who benefits from each item:
+
+- **Whole team**: knowledge that any developer working in this codebase needs. Goes in project CLAUDE.md.
+- **Personal cross-project**: knowledge that is specific to the user's workflow or preferences but applies across projects. Goes in the user's global CLAUDE.md.
+- **Personal persistent**: knowledge that the user should remember but that is not relevant to other developers. Goes in the user's Claude Code memory.
+- **Project documentation**: knowledge that belongs in the repo as formal documentation (ADRs, runbooks, onboarding guides). Goes in `docs/`.
+- **Agent-specific**: knowledge that individual Forge agents should internalize for better performance. Goes in agent prompt files or skill files.
+
+## Knowledge Distribution Priority
+
+Distribute knowledge to the location with the highest impact first. The priority order reflects how frequently each location is read and by whom.
+
+### Priority 1: Project CLAUDE.md
+
+**Path**: `{project-root}/CLAUDE.md`
+
+**Audience**: every developer and every AI agent that works in this project.
+
+**Impact**: highest. This file is loaded into every Claude Code session for this project. A gotcha recorded here prevents every future developer from hitting the same issue.
+
+**What belongs here**:
+
+- Technical gotchas specific to this project's stack and configuration.
+- Naming conventions for this project (database, Helm, K8s, ECR, etc.).
+- Patterns established in this codebase that differ from framework defaults.
+- Infrastructure dependencies and constraints (cluster limits, service endpoints, credential sources).
+- Build/test/deploy commands and gotchas.
+
+**What does NOT belong here**:
+
+- Personal preferences that only apply to one developer.
+- General programming advice that any experienced developer knows.
+- Temporary information (current sprint goals, in-progress work).
+- Verbose explanations — link to docs for details, keep CLAUDE.md concise.
+
+### Priority 2: User's Global CLAUDE.md
+
+**Path**: `~/.claude/CLAUDE.md`
+
+**Audience**: the user, across all projects.
+
+**Impact**: high. Loaded into every Claude Code session for this user regardless of project. Captures cross-cutting personal workflow preferences.
+
+**What belongs here**:
+
+- Stack preferences (NestJS + Drizzle, not Express + Prisma).
+- Workflow preferences (autonomous execution, parallel dispatch, commit cadence).
+- Cross-project gotchas (SWC behavior, Docker VHDX management, PowerShell-via-Bash escaping).
+- Naming conventions that span projects (Synapse naming table if it applies beyond one repo).
+- IaC repo locations and the "never use CLI" rule.
+
+**What does NOT belong here**:
+
+- Project-specific configuration or conventions.
+- Information that is already in a project CLAUDE.md (avoid duplication).
+- Exhaustive lists — keep it scannable.
+
+### Priority 3: User's Claude Code Memory
+
+**Path**: `~/.claude/memory/`
+
+**Audience**: the user's AI assistant, persistently.
+
+**Impact**: moderate. Persists across sessions and projects but is not visible to team members.
+
+**What belongs here**:
+
+- Personal context that improves AI assistance: preferred explanation style, common tasks, frequently used commands.
+- Reminders about past issues that recur sporadically.
+- Context about the user's environment (Windows 11, specific tool versions, local paths).
+
+### Priority 4: Project Documentation
+
+**Path**: `{project-root}/docs/decisions/`, `{project-root}/docs/learnings/`
+
+**Audience**: the development team, reviewable in PRs and onboarding.
+
+**Impact**: moderate-to-low for daily development, high for onboarding and architectural review.
+
+**What belongs here**:
+
+- Architectural Decision Records (ADRs) — formal documentation of significant technical decisions.
+- Learnings documents — longer-form writeups of complex problems and their solutions.
+- Runbooks — step-by-step guides for operational procedures.
+- Onboarding guides — what a new developer needs to know to be productive.
+
+### Priority 5: Agent-Specific Memory
+
+**Path**: Agent prompt files or skill files within the Forge plugin.
+
+**Audience**: individual Forge agents.
+
+**Impact**: low frequency (only affects Forge workflows) but high specificity (directly improves agent performance).
+
+**What belongs here**:
+
+- Agent-specific anti-patterns learned from past failures.
+- Calibration data: which types of tasks this agent handles well vs. needs more guidance.
+- Prompt refinements based on observed output quality.
+
+## CLAUDE.md Writing Guidelines
+
+CLAUDE.md is the most impactful knowledge distribution channel. Every word in it is loaded into every session. Write accordingly.
+
+### Be Concise
+
+Every line in CLAUDE.md costs tokens in every session. A 500-line CLAUDE.md loads 500 lines of context whether relevant or not. Optimize for density.
+
+- One line per gotcha when possible. Use the pattern: **Bold title** — explanation with the "why."
+- Use tables for structured data. Tables are denser than bullet lists for multi-field items.
+- Eliminate filler words. Not "It is important to note that..." — just state the fact.
+
+### Structure for Scannability
+
+Group related items under clear headers. An agent looking for NestJS gotchas should find them all under `## NestJS + Drizzle Gotchas`, not scattered across the file.
+
+Recommended section structure:
+
+```markdown
+## Stack
+## Workflow Preferences
+## {Stack} Gotchas Learned
+## Infrastructure Gotchas Learned
+## Naming Conventions
+## {Feature} Patterns
+```
+
+### Include the "Why"
+
+A rule without rationale is a rule that will be ignored or misapplied.
+
+Bad: `Use postgres driver, not pg.`
+Good: `Use postgres (postgres.js) driver with Drizzle, not pg -- lighter, fewer deps.`
+
+Bad: `Run db:generate before db:migrate.`
+Good: `Drizzle migrations: must run db:generate before db:migrate -- there is no auto-generate on migrate.`
+
+The "why" enables the reader to know when the rule applies and when it might not. Without it, the rule is cargo-culted.
+
+### Remove Outdated Entries
+
+Knowledge that is no longer true is actively harmful. It causes agents and developers to follow obsolete patterns, work around bugs that have been fixed, or avoid approaches that are now valid.
+
+When curating knowledge:
+
+- Check each existing entry against current project state. Has the dependency been updated? Has the bug been fixed? Has the convention changed?
+- Remove entries that no longer apply. Do not just add new entries — prune old ones.
+- If an entry is uncertain, mark it with a date: `(as of 2026-02-25)` so future curators know when it was last verified.
+
+### Avoid Duplication
+
+If the same knowledge appears in both the project CLAUDE.md and the user's global CLAUDE.md, it will be loaded twice in every session for that user in that project. Decide where it belongs based on audience:
+
+- Specific to this project? Project CLAUDE.md only.
+- Applies to the user across projects? Global CLAUDE.md only.
+- Applies to the team AND is cross-project? This is rare — usually it belongs in the project CLAUDE.md with a brief mention in the global file linking to the convention.
+
+## ADR (Architectural Decision Record) Format
+
+For significant architectural decisions, create a formal ADR in:
+
+```
+docs/decisions/NNNN-{title}.md
+```
+
+Where `NNNN` is a zero-padded sequential number and `{title}` is lowercase-kebab-case.
+
+### ADR Template
+
+```markdown
+# NNNN. {Decision Title}
+
+**Date**: YYYY-MM-DD
+**Status**: Proposed | Accepted | Deprecated | Superseded by [NNNN]
+**Deciders**: {who made the decision}
+
+## Context
+
+{What is the problem or situation that requires a decision? Include technical
+constraints, business requirements, and relevant history.}
+
+## Decision
+
+{What was decided. State it clearly and unambiguously.}
+
+## Alternatives Considered
+
+### Option A: {name}
+{Description, pros, cons}
+
+### Option B: {name}
+{Description, pros, cons}
+
+[Additional options as needed]
+
+## Consequences
+
+### Positive
+- {benefit 1}
+- {benefit 2}
+
+### Negative
+- {tradeoff 1}
+- {tradeoff 2}
+
+### Risks
+- {risk and mitigation}
+
+## References
+
+- {links to relevant documentation, RFCs, prior art}
+```
+
+### When to Write an ADR
+
+Create an ADR when:
+
+- The decision affects system architecture (module boundaries, communication patterns, data storage).
+- The decision is hard to reverse (database schema, public API shape, infrastructure topology).
+- The decision was debated or multiple alternatives were seriously considered.
+- The decision would surprise a new team member reviewing the codebase.
+
+Do NOT write an ADR for:
+
+- Trivial implementation choices (variable names, minor refactors).
+- Decisions that are already enforced by tooling (linter rules, type system).
+- Decisions that are obvious given the project's established patterns.
+
+## When to Update vs. When to Create New Entries
+
+### Update an Existing Entry When:
+
+- New information refines an existing gotcha (additional detail, a better workaround, an updated version that changes behavior).
+- A convention evolves (naming pattern changes from `dk-one-tools` to `dk-synapse`).
+- A gotcha is resolved (dependency update fixes the bug — remove the workaround, note it is fixed).
+
+### Create a New Entry When:
+
+- An entirely new gotcha, pattern, or convention is discovered.
+- A new category of knowledge emerges (e.g., first time working with a new technology).
+- An existing decision is superseded (create a new ADR, mark the old one as superseded).
+
+### Never:
+
+- Create duplicate entries for the same knowledge item. If it exists, update it.
+- Leave contradictory entries. If a new entry contradicts an old one, remove or update the old one.
+- Add entries without checking for existing related entries first.
+
+## Deduplication Protocol
+
+Before adding any knowledge item, search for existing related entries:
+
+1. **Search project CLAUDE.md** for keywords related to the new item.
+2. **Search global CLAUDE.md** for the same keywords.
+3. **Search `docs/decisions/`** for related ADRs.
+4. **Search `docs/learnings/`** for related writeups.
+
+If a related entry exists:
+
+- If the new knowledge extends it, update the existing entry.
+- If the new knowledge contradicts it, verify which is correct, then update or remove the outdated entry.
+- If the new knowledge is a subset of it, do not add a new entry — the existing one already covers it.
+
+## Verification Protocol
+
+Before recording a knowledge item, verify it against actual project behavior. Do not record hearsay, assumptions, or outdated information.
+
+### Verification Methods
+
+- **For gotchas**: reproduce the issue. If it cannot be reproduced, it may have been fixed. Verify against the current dependency version and configuration.
+- **For patterns**: confirm the pattern is actually used in the codebase. Search for its implementation. If it was planned but never implemented, note that distinction.
+- **For conventions**: confirm the convention is followed consistently. If some files follow it and others do not, the convention is aspirational, not established. Note the inconsistency.
+- **For decisions**: confirm the decision was actually implemented. If the architecture document says "use WebSocket" but the code uses polling, the decision was not implemented and should not be recorded as fact.
+
+### Staleness Detection
+
+Knowledge items become stale when:
+
+- Dependencies are updated (new major version may fix bugs, change APIs).
+- Infrastructure changes (cluster migration, new service mesh, updated Kubernetes version).
+- Team practices evolve (workflow that was manual is now automated).
+- Features are added or removed (gotchas for removed features are noise).
+
+During curation, check the date on each existing entry. If an entry is older than 3 months with no verification, flag it for review. If older than 6 months, verify it or remove it.
+
+## Curation Workflow Summary
+
+1. **Extract**: review all workflow outputs and identify knowledge items.
+2. **Categorize**: assign type (gotcha, pattern, convention, decision) and audience (team, personal, agent).
+3. **Deduplicate**: search existing knowledge stores for related entries.
+4. **Verify**: confirm the knowledge item against actual current behavior.
+5. **Distribute**: write the item to the highest-priority appropriate location.
+6. **Prune**: remove or update any existing entries that the new knowledge supersedes or contradicts.
+7. **Report**: summarize what was curated and where it was distributed in the workflow handoff.

package/plugin/skills/learn/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: learn
+description: Save or search project learnings, decisions, and gotchas. Auto-detects whether to save or search based on your prompt.
+version: 0.1.0
+---
+
+# /learn — Project Memory
+
+Save and search observations, decisions, and gotchas. One command, auto-detects intent.
+
+## Intent Detection
+
+### Save Intent
+
+**Signals**: starts with "learn this:", "save:", "note:", contains "don't forget", "for next time", or the prompt is a declarative statement/fact.
+
+```
+/learn SWC hoists all require() calls above executable code in CJS output
+/learn Decision: we chose postgres.js over pg for lighter deps
+/learn save: the auth middleware must run before the rate limiter
+```
+
+**Action**: Call `mcp__dk-forge__save_observation` with the content.
+
+Auto-classify from the content:
+- "Decision: ..." → `type: semantic`, `category: decision`
+- "Gotcha: ..." / "Watch out for ..." → `type: semantic`, `category: gotcha`
+- "To do X, first ..." → `type: procedural`, `category: pattern`
+- Plain statement → `type: semantic`
+
+Parameters:
+- **importance**: Default 0.5. Set higher (0.8+) for critical discoveries.
+- **tags**: Infer stack/domain tags from content (e.g., `["nestjs", "drizzle"]`).
+- **symbols**: Code symbols mentioned (e.g., `["AuthService"]`). Links to the code graph.
+
+After saving, confirm with the observation ID.
+
+### Search Intent
+
+**Signals**: contains a question mark, starts with "what did we", "do we know", "remember when", "anything about", "last time we", or is phrased as a question.
+
+```
+/learn what did we find about authentication?
+/learn anything about SWC issues?
+/learn remember when we fixed the docker volume problem?
+```
+
+**Action**: Call `mcp__dk-forge__search_memory` with the query.
+
+Present results with:
+1. **Content** — the observation text.
+2. **Category** — gotcha, decision, pattern, etc.
+3. **When** — relative timestamp.
+4. **Relevance score**.
+
+### Session Context
+
+**Signals**: "recent", "last session", "what happened", "where did we leave off".
+
+```
+/learn recent
+/learn what happened last session?
+```
+
+**Action**: Call `mcp__dk-forge__get_session_context` to retrieve observations from current and recent sessions.
+
+## Boosting
+
+When a recalled learning proves valuable, call `mcp__dk-forge__boost_knowledge` with its ID to increase its visibility in future searches.

package/plugin/skills/mcp-integration/.skillfish.json

@@ -0,0 +1,10 @@
+{
+  "version": 2,
+  "name": "mcp-integration",
+  "owner": "anthropics",
+  "repo": "claude-code",
+  "path": "plugins/plugin-dev/skills/mcp-integration",
+  "branch": "main",
+  "sha": "3e57353b7b88f20216666d616b14015f3574554c",
+  "source": "manual"
+}