forge-server 0.1.0

package/plugin/skills/agent-handoff/SKILL.md

@@ -0,0 +1,335 @@
+---
+name: agent-handoff
+description: >
+  This skill should be used when transitioning work between forge agents — passing context from
+  one phase to the next, summarizing completed work, or preparing input for the next agent in
+  the workflow. Used by all forge agents.
+user-invocable: false
+---
+
+# Agent Handoff Skill
+
+## Document-Based Handoff Principle
+
+Agents in the Forge system do not share conversation context. They do not pass memory, chat history, or internal state between each other. All inter-agent communication happens through plan documents written to the filesystem.
+
+This is by design, not by limitation. Document-based handoff produces:
+
+- **Auditability**: every decision, every handoff, every scope change is recorded in a document that humans and agents can review.
+- **Resumability**: if a workflow is interrupted (crash, timeout, user stepping away), any agent can pick up from the last written document without loss of context.
+- **Parallelism**: multiple agents can read the same plan documents simultaneously without contention, because documents are write-once-then-read-many during any given phase.
+- **Token efficiency**: instead of forwarding thousands of tokens of conversation history, write a structured summary to disk and let the next agent read only what it needs.
+
+The cardinal rule: **if information is not written to a plan document, it does not exist for the next agent.** Verbal agreements, in-context decisions, and implicit assumptions that are not persisted are lost at handoff.
+
+## What to Write to Documents
+
+Every agent that produces work must write its findings, decisions, and deliverables to the appropriate plan document before handing off. The following categories of information must always be captured:
+
+### Decisions Made
+
+Record every non-trivial decision with its rationale. A decision without rationale is useless to the next agent — it cannot tell whether the decision was a careful choice or an arbitrary default.
+
+Format:
+
+```
+| Date | Decision | Rationale | Decided By |
+|------|----------|-----------|------------|
+| 2026-02-25 | Use WebSocket for real-time updates | Polling at 1s interval would create 86K requests/user/day; WebSocket reduces to one persistent connection | Architect |
+| 2026-02-25 | Store media in S3 with presigned URLs | Direct upload to S3 avoids proxying large files through the API server, reducing memory pressure | Architect |
+```
+
+### Constraints Identified
+
+New constraints discovered during work that were not in the original vision. These are critical for downstream agents.
+
+Examples:
+
+- "The existing `users` table uses UUID v4 primary keys, so all foreign keys referencing it must also be UUID."
+- "The Keycloak OIDC provider returns `sub` as the user identifier, not `email`. Auth module must use `sub` for identity mapping."
+- "The target Kubernetes cluster has a 512Mi memory limit per pod. The application must stay within this envelope."
+
+### Open Questions
+
+Questions that arose during work and could not be answered from existing documents. These must be surfaced — not buried in agent output — so the Strategist or user can resolve them.
+
+Format:
+
+```
+## Open Questions
+- Should rate limiting apply per-user or per-API-key? (Affects whether we track limits in session store or a separate Redis key space)
+- Is the 30-day retention policy a hard requirement, or can we make it configurable? (Affects schema design)
+- Does the media upload flow need virus scanning? (Affects architecture — adds an async processing step)
+```
+
+### Deliverables Produced
+
+List every file created or modified, with a one-line description of what it contains. The next agent should not have to read every file to understand what was produced.
+
+## What to Summarize (Not Copy)
+
+Certain types of information are too large or too detailed to include verbatim in handoff documents. Summarize these instead:
+
+- **Large code blocks**: do not paste entire files into plan documents. Instead, reference the file path and describe what the code does. Example: "Created `src/modules/auth/auth.service.ts` — handles JWT validation, token refresh, and session management. Uses `jsonwebtoken` with RS256 signing."
+- **Long conversations**: if the Strategist had a multi-turn interview with the user, summarize the key decisions and requirements. Do not paste the full transcript.
+- **Debugging sessions**: if the Debugger traced a complex issue, summarize the root cause, the fix applied, and the regression test added. Do not paste the full stack trace analysis.
+- **Research findings**: if an agent investigated multiple approaches, summarize the options considered, the one chosen, and why. Do not paste all the documentation links and comparison notes.
+
+The test for good summarization: can the next agent understand what happened and why without asking any follow-up questions? If yes, the summary is sufficient.
+
+## Handoff Document Locations
+
+All plan documents live under a date-stamped directory:
+
+```
+docs/plans/YYYY-MM-DD-{TITLE}/
+```
+
+Where `YYYY-MM-DD` is the project start date and `{TITLE}` is a lowercase-kebab-case slug derived from the feature name.
+
+### Standard Document Set
+
+| Document | Author | Purpose |
+|----------|--------|---------|
+| `vision.md` | Strategist | Problem statement, goals, non-goals, success criteria, user stories, constraints, risks |
+| `requirements.md` | Strategist / Product Manager | Detailed functional and non-functional requirements, acceptance criteria |
+| `xd-plan.md` | Designer | Experience design: page layouts, component hierarchy, interaction patterns, responsive behavior |
+| `architecture.md` | Architect | System design: module structure, API contracts, data models, infrastructure, sequence diagrams |
+| `test-plan.md` | QA Strategist | Test pyramid allocation, test cases by layer, test data requirements, coverage targets |
+
+### Agent Output Directory
+
+Individual agent outputs from parallel dispatch go in:
+
+```
+docs/plans/YYYY-MM-DD-{TITLE}/agent-output/
+```
+
+Each agent writes its completion report to:
+
+```
+docs/plans/YYYY-MM-DD-{TITLE}/agent-output/{agent-type}-{scope}.md
+```
+
+Example: `agent-output/backend-auth.md`, `agent-output/frontend-dashboard.md`, `agent-output/data-content-schema.md`.
+
+## Agent-to-Agent Handoff Format
+
+When an agent completes its work and hands off to the next agent (or reports back to the Strategist), use this structured format:
+
+```markdown
+# Handoff: {Phase/Task Name}
+
+**FROM**: {agent name} (e.g., Architect)
+**TO**: {next agent name or "Strategist for review"}
+**DATE**: YYYY-MM-DD
+**STATUS**: Complete | Partial | Blocked
+
+## Deliverables
+
+| File | Action | Description |
+|------|--------|-------------|
+| `src/modules/auth/auth.module.ts` | Created | NestJS module with JWT, session, and RBAC providers |
+| `src/modules/auth/auth.service.ts` | Created | Core auth logic: login, refresh, validate, revoke |
+| `src/common/dto/auth.dto.ts` | Created | Shared DTOs: LoginRequest, LoginResponse, TokenPayload |
+| `drizzle/migrations/0001_create_users.sql` | Created | Users table with UUID PK, email unique, hashed password |
+
+## Decisions Made
+
+| Decision | Rationale |
+|----------|-----------|
+| RS256 for JWT signing | Asymmetric keys allow token verification without sharing the signing secret |
+| Refresh tokens stored in DB, not cookies | Enables server-side revocation and multi-device session management |
+| 15-minute access token TTL | Balances security (short window) with UX (infrequent re-auth) |
+
+## Constraints Discovered
+
+- The Keycloak OIDC `sub` claim is a UUID, not an email. All downstream identity references must use this UUID.
+- Existing database uses `timestamptz` for all date columns. New tables must follow this convention.
+
+## Open Questions
+
+- Should failed login attempts trigger a CAPTCHA after N attempts, or just account lockout? (Needs Strategist/user input)
+- Is there a requirement for "remember me" functionality extending the session beyond the default TTL?
+
+## Recommendations for Next Agent
+
+- The Builder implementing the auth module should read `architecture.md` section "Authentication Flow" before starting.
+- The Tester should prioritize token expiration and refresh edge cases — these are the most security-critical paths.
+- The Frontend agent should use the `TokenPayload` type from `src/common/dto/auth.dto.ts` for client-side token decoding.
+
+## Integration Points
+
+- `auth.module.ts` must be registered in `app.module.ts` (not done yet — reserved for the integration phase).
+- The `AuthGuard` exported from this module should be applied globally or per-controller by the Builder.
+- The `users` table created by migration 0001 is referenced by: content module (author FK), media module (uploader FK).
+```
+
+### Minimal Handoff (For Small Tasks)
+
+For small, single-agent tasks that do not warrant a full handoff document:
+
+```markdown
+# Handoff: {Task Name}
+
+**FROM**: {agent name}
+**STATUS**: Complete
+**DELIVERABLES**: {file1}, {file2}, {file3}
+**DECISIONS**: {one-line per decision}
+**OPEN QUESTIONS**: None
+**RECOMMENDATIONS**: {one-line for next agent}
+```
+
+## Receiving Protocol
+
+When an agent receives a handoff (either a direct handoff from another agent or a task dispatch from the Strategist/Architect), follow this protocol before doing any work:
+
+### Step 1: Read All Relevant Plan Documents
+
+Read the documents that establish context for the task:
+
+1. `vision.md` — understand the project goals and constraints.
+2. `architecture.md` — understand the technical design and where this task fits.
+3. `test-plan.md` — understand the testing expectations (if implementing or testing).
+4. `xd-plan.md` — understand the UX design (if working on frontend).
+5. Any prior handoff documents in `agent-output/` that are relevant to this task.
+
+### Step 2: Acknowledge Scope
+
+Before starting work, internally verify:
+
+- What exactly is the scope of this task? (Files to create/modify, boundaries)
+- What is explicitly out of scope? (Files owned by other agents, deferred work)
+- What decisions have already been made that constrain this work?
+- What shared types/interfaces/contracts must be used (not recreated)?
+
+### Step 3: Flag Concerns
+
+If anything in the handoff is unclear, contradictory, or seems wrong, flag it before proceeding:
+
+- If the architecture document specifies a pattern that conflicts with a project convention, raise it.
+- If the scope appears to overlap with another agent's scope, raise it.
+- If a required dependency (shared type, base table, configuration) does not exist yet, raise it.
+- If the task seems larger than a single dispatch unit, raise it.
+
+Raise concerns by writing them to the handoff output document under "Concerns Raised" and, if the concern is blocking, escalating to the Strategist.
+
+### Step 4: Begin Work
+
+Only after reading, acknowledging, and flagging proceed with implementation. Work within the stated scope. Do not expand scope without escalation.
+
+## Token Efficiency
+
+Context windows are finite and expensive. The handoff system is designed to minimize token waste.
+
+### Rules for Token-Efficient Handoff
+
+1. **Never pass raw conversation history between agents.** A 50-turn debugging conversation might be 20K tokens. The handoff summary should be 500 tokens: root cause, fix, regression test, done.
+
+2. **Write findings to documents, not to parent context.** When a sub-agent finishes, it writes its results to a file. The orchestrating agent reads the file. The orchestrating agent does NOT need to include the sub-agent's full output in its own context — just the file path and a status summary.
+
+3. **Reference, do not inline.** Instead of pasting the contents of `architecture.md` into a task prompt, instruct the agent: "Read `docs/plans/2026-02-25-notifications/architecture.md`, section 'WebSocket Gateway'." The agent reads what it needs; the prompt stays small.
+
+4. **Summarize at phase boundaries.** At the end of each Forge phase (Vision, Architecture, Implementation, Quality, Documentation, Deployment), the leading agent writes a phase summary to the plan directory. Subsequent phases read the summary, not the full working history.
+
+5. **Prune completed handoff data.** Once a handoff is acknowledged and work begins, the receiving agent does not need to keep the handoff document in its active context. Read it once, extract what is needed, proceed.
+
+### What Belongs in Context vs. in Documents
+
+| In Agent Context (prompt) | In Plan Documents (filesystem) |
+|--------------------------|-------------------------------|
+| Current task description | Full architecture design |
+| Immediate scope boundaries | Complete vision document |
+| Key constraints (3-5 bullets) | Detailed test plan |
+| Shared type definitions (if small) | All agent output reports |
+| Error messages being debugged | Historical decision logs |
+
+## Escalation Protocol
+
+Not all handoffs go smoothly. When an agent encounters a situation it cannot resolve within its scope, escalate to the Strategist.
+
+### When to Escalate
+
+- **Scope change detected.** The work required to fulfill the task exceeds or differs from the original scope defined in the architecture/vision documents. Example: "The architecture says to use REST, but the requirements imply real-time bidirectional communication — this needs a WebSocket design that is not in the architecture."
+- **Blocker encountered.** A dependency is missing, a service is unavailable, a required decision has not been made, or a technical constraint makes the planned approach impossible.
+- **Conflicting requirements.** Two plan documents (or two sections of the same document) specify contradictory behavior. Example: "The vision says 'offline-first' but the architecture shows a stateless API with no local storage."
+- **Quality threshold not met.** The Inspector or Tester finds issues that cannot be fixed within the current agent's scope (e.g., a security vulnerability that requires architectural change).
+- **User input required.** A decision is too impactful, too irreversible, or too far from established patterns to make autonomously.
+
+### Escalation Format
+
+```markdown
+# ESCALATION
+
+**FROM**: {agent name}
+**TO**: Strategist
+**PRIORITY**: Blocking | High | Low
+**DATE**: YYYY-MM-DD
+
+## Issue
+
+{Clear, concise description of the problem}
+
+## Context
+
+{What task was being performed, what was discovered}
+
+## Options Considered
+
+| Option | Pros | Cons |
+|--------|------|------|
+| A: {description} | ... | ... |
+| B: {description} | ... | ... |
+
+## Recommendation
+
+{Agent's recommended option, if any, with rationale}
+
+## Impact if Unresolved
+
+{What happens if this escalation is not resolved — blocked agents, degraded quality, scope gap}
+```
+
+### Escalation Flow
+
+1. Agent writes escalation to `docs/plans/YYYY-MM-DD-{TITLE}/escalations/{agent}-{topic}.md`.
+2. Agent pauses work on the blocked item (continues on unblocked items if any).
+3. Strategist reviews the escalation, consults the user if needed, and writes a resolution directive.
+4. Agent reads the resolution and resumes work.
+
+## Handoff Anti-Patterns
+
+### "Just Read My Code"
+
+Never hand off by pointing to code files and saying "the implementation speaks for itself." Code captures what was built, not why. The receiving agent needs rationale, constraints, and context that code alone does not provide.
+
+### Context Dump
+
+Never hand off by pasting the entire conversation history or every file that was touched. This wastes tokens and forces the receiving agent to sift through noise. Summarize, structure, and distill.
+
+### Implicit Scope
+
+Never hand off without explicit scope boundaries. "Build the frontend" is not a handoff. "Build the dashboard page per xd-plan.md section 3, creating files in `src/pages/dashboard/`, using shared components from `src/components/ui/`, consuming the `/api/v1/metrics` endpoint defined in architecture.md section 5.2" is a handoff.
+
+### Missing Decisions
+
+Never hand off with undocumented decisions. If the Architect chose PostgreSQL over MongoDB, or chose WebSocket over SSE, or chose UUID over auto-increment — it must be in the handoff with rationale. The Builder should not rediscover or re-debate these decisions.
+
+### Orphaned Open Questions
+
+Never hand off open questions without directing them to someone. Each open question should name who is expected to resolve it (Strategist, user, next agent) and what the default assumption is if it remains unresolved.
+
+## Handoff Verification Checklist
+
+Before finalizing a handoff, verify:
+
+- [ ] All deliverable files are listed with paths and descriptions.
+- [ ] All non-trivial decisions are recorded with rationale.
+- [ ] All new constraints are documented.
+- [ ] All open questions name an owner and a default assumption.
+- [ ] The next agent's scope is explicitly defined (what to do AND what not to do).
+- [ ] Shared dependencies are identified (files to import, not recreate).
+- [ ] The handoff document is written to the correct path under `docs/plans/`.
+- [ ] The handoff status is accurate (Complete, Partial, or Blocked).
+- [ ] Recommendations for the receiving agent are actionable and specific.
+- [ ] No raw conversation history or large code blocks are included — only summaries and references.

package/plugin/skills/anti-stub/SKILL.md

@@ -0,0 +1,317 @@
+---
+name: anti-stub
+description: This skill should be used when writing production code, reviewing code for completeness, or verifying that implementations are fully wired. Used by the inspector agent for enforcement and by all implementation agents for self-discipline. Detects and prevents incomplete implementations, placeholder returns, and TODO stubs.
+user-invocable: false
+---
+
+# Anti-Stub Skill
+
+## Purpose
+
+Provide a rigorous detection and prevention methodology for incomplete implementations, placeholder returns, TODO stubs, and fake data in production code. Apply this skill when writing production code (as a self-check), when reviewing code for completeness, and when verifying that a feature is truly implemented — not merely sketched. Stubs are the most insidious form of technical debt because they silently masquerade as completed work.
+
+---
+
+## Why Stubs Are Dangerous
+
+### False Confidence in the Test Suite
+
+Tests that pass against stubbed implementations create an illusion of correctness. The test suite is green, code review looks clean, and the feature appears done. But the stub returns hardcoded data that happens to match the test's expectations. When real data flows through the system, the stub fails — often in production, long after the team has moved on.
+
+### Cascading Dependency Debt
+
+Other code builds on stubbed interfaces. If `getUserPermissions()` returns a hardcoded `['admin']`, the authorization layer, the UI, and the audit log all develop around that assumption. When the real implementation arrives, every dependent system needs reworking. The longer the stub exists, the more code depends on it, and the more expensive the replacement becomes.
+
+### Stubs Get Forgotten
+
+"Temporary" becomes permanent. Every stub is created with the intention of replacing it later. Most are not tracked in any task system. They hide in utility functions, seed files, and service implementations. Within weeks, nobody remembers that the function is a stub. Within months, the developer who created it has moved on to other work. The stub becomes a permanent fixture of the codebase.
+
+### Stubs Hide Missing Requirements
+
+The existence of a function implies the feature exists. If `calculateShippingCost()` returns `0`, the product manager sees shipping cost on the invoice and assumes it works. The missing requirement — "integrate with the shipping rate API" — never surfaces because the stub gives the appearance of completion.
+
+---
+
+## What Stubs Look Like: Detection Patterns
+
+### Hardcoded Return Values
+
+Functions that return static, predetermined data instead of computing or fetching real results:
+
+```typescript
+// STUB: Returns empty collection instead of querying
+async getUsers(): Promise<User[]> {
+  return [];
+}
+
+// STUB: Returns hardcoded object instead of database lookup
+async getConfig(): Promise<AppConfig> {
+  return { theme: 'dark', language: 'en' };
+}
+
+// STUB: Returns null instead of implementing logic
+async calculateDiscount(order: Order): Promise<number | null> {
+  return null;
+}
+
+// STUB: Returns placeholder string
+async generateReport(): Promise<string> {
+  return 'TODO';
+}
+```
+
+### TODO/FIXME/HACK Comments in Production Code
+
+Any comment containing keywords that signal incomplete work:
+
+- `TODO` — acknowledged incompleteness
+- `FIXME` — acknowledged incorrectness
+- `HACK` — acknowledged inappropriate implementation
+- `PLACEHOLDER` — explicitly temporary
+- `STUB` — explicitly unimplemented
+- `NOT IMPLEMENTED` — explicitly unimplemented
+- `TEMP` — explicitly temporary (when used to mark temporary code, not temporary data)
+
+These comments are acceptable in test files, in documentation, and in issue trackers. They are NOT acceptable in production source code that will be deployed.
+
+### Empty or Swallowed Error Handlers
+
+```typescript
+// STUB: Swallows errors silently
+try {
+  await riskyOperation();
+} catch (e) {}
+
+// STUB: Logs but does not handle
+try {
+  await riskyOperation();
+} catch (e) {
+  console.log(e);
+}
+
+// STUB: Returns default value on error instead of handling
+try {
+  return await fetchData();
+} catch (e) {
+  return [];  // Silently returns empty, caller never knows it failed
+}
+```
+
+### Hardcoded Data in Production Services
+
+Mock data, seed data, or fake data embedded in production service files:
+
+```typescript
+// STUB: Hardcoded user list instead of database query
+const users = [
+  { id: 1, name: 'Test User', email: 'test@example.com' },
+  { id: 2, name: 'Admin', email: 'admin@example.com' },
+];
+
+// STUB: Hardcoded configuration instead of config service
+const API_URL = 'http://localhost:3000';
+```
+
+### Placeholder UI Content
+
+```tsx
+// STUB: Placeholder text
+<p>Lorem ipsum dolor sit amet</p>
+
+// STUB: Unimplemented page
+<div>Coming soon</div>
+
+// STUB: Feature facade
+<div>Under construction</div>
+
+// STUB: Fake data in component
+const items = ['Item 1', 'Item 2', 'Item 3'];
+```
+
+### Not-Implemented Throw Patterns
+
+```typescript
+// STUB: Function signature exists but body is a throw
+async processPayment(payment: Payment): Promise<Receipt> {
+  throw new Error('Not implemented');
+}
+
+// STUB: Method exists but does nothing
+onNotification(notification: Notification): void {
+  // will implement later
+}
+```
+
+### API Endpoints with Empty Bodies
+
+```typescript
+// STUB: Returns 200 but no real data
+@Get('analytics')
+async getAnalytics() {
+  return {};
+}
+
+// STUB: Accepts input but ignores it
+@Post('webhook')
+async handleWebhook(@Body() body: any) {
+  return { received: true };
+}
+```
+
+---
+
+## Anti-Stub Rules
+
+### Rule 1: Every Function Must Return Real Data from a Real Source
+
+If a function queries users, it must query the actual database (or data layer). If a function calculates a total, it must perform the actual calculation. If a function fetches external data, it must call the actual external API. No hardcoded returns. No inline mock data.
+
+### Rule 2: Every API Endpoint Must Connect to a Real Service
+
+Every controller method must invoke the service layer, which must invoke the data layer. An endpoint that returns a hardcoded response is not an endpoint — it is a lie. Leave the endpoint out entirely until the service is ready.
+
+### Rule 3: Every UI Component Must Render Real Content
+
+Components render data from props, from state, or from API responses. Never from hardcoded arrays or objects defined inside the component. Proper loading states ("Loading...") and empty states ("No items found") are real UI features, not stubs — they handle actual application conditions.
+
+### Rule 4: Every Error Handler Must Handle the Error
+
+Error handling means one or more of: logging the error with context, retrying the operation, surfacing the error to the user, triggering a fallback behavior, or propagating the error up the call stack. An empty catch block is not error handling. A `console.log` is not error handling.
+
+### Rule 5: If the Real Implementation Is Not Ready, Do Not Create the Stub
+
+The absence of a function is honest. A stub function is dishonest. If the payment processing integration is not ready, do not create a `processPayment` function that returns a fake receipt. Leave the payment module out of the codebase entirely until it can be implemented for real.
+
+This is counterintuitive — it feels like "progress" to create the stub. But progress that creates false confidence is negative progress.
+
+### Rule 6: If a Dependency Is Unavailable, Throw a Clear Error
+
+When a function cannot be implemented because an external dependency (API, service, database table) does not exist yet, throw an explicit error instead of returning fake data:
+
+```typescript
+async getExchangeRate(currency: string): Promise<number> {
+  throw new NotImplementedException(
+    'Exchange rate API integration pending — blocked by PROJ-1234'
+  );
+}
+```
+
+This is honest. It fails loudly. It includes a tracking reference. It cannot be mistaken for a working implementation.
+
+---
+
+## Grep Patterns for Detection
+
+Use these patterns to scan a codebase for stubs. Run these against production source files only (exclude test files, fixture files, and seed files).
+
+### Comment-Based Stubs
+
+```
+TODO|FIXME|HACK|PLACEHOLDER|STUB|NOT.IMPLEMENTED|TEMP.FIX|WILL.IMPLEMENT
+```
+
+### Return-Based Stubs
+
+```
+return \[\]|return \{\}|return null|return ''|return 'TODO'|return undefined
+```
+
+### Content-Based Stubs
+
+```
+lorem ipsum|coming soon|under construction|placeholder text|sample data
+```
+
+### Error-Handling Stubs
+
+```
+catch.*\{\s*\}|catch.*console\.log
+```
+
+### Throw-Based Stubs
+
+```
+throw new Error\('Not implemented|throw new NotImplementedException
+```
+
+### Hardcoded Localhost
+
+```
+localhost:\d{4}|127\.0\.0\.1:\d{4}
+```
+
+When running these patterns, review each match in context. Not every match is a stub — the patterns cast a wide net intentionally. A `return []` in a function that genuinely finds no results is not a stub. A `return []` in a function that should be querying a database is.
+
+---
+
+## What IS Acceptable
+
+### Mocks in Test Files
+
+Test files (`*.spec.ts`, `*.test.ts`, `*.test.tsx`) exist to isolate behavior. Mocks, stubs, and fake data in test files are correct and necessary. The anti-stub rules apply to production source code only.
+
+### Loading and Empty States in UI
+
+A component that renders "Loading..." while waiting for an API response is not a stub — it is a real feature that handles a real application state. Similarly, "No results found" for an empty search result is real behavior. The distinction: stubs replace real functionality; loading and empty states augment it.
+
+### Feature Flags
+
+A feature flag that gates an incomplete feature is acceptable — the code behind the flag is real (or absent), and the flag explicitly communicates that the feature is not yet available. The stub problem is about deception; a feature flag is transparent.
+
+```typescript
+// ACCEPTABLE: Feature flagged, clearly gated
+if (featureFlags.isEnabled('advanced-analytics')) {
+  return this.analyticsService.getAdvancedReport(params);
+}
+return this.analyticsService.getBasicReport(params);
+```
+
+### Graceful Degradation
+
+When an external service is down and the system falls back to cached data or reduced functionality, that is not a stub — it is resilience. The key difference: graceful degradation is an intentional, documented, monitored behavior. A stub is an undocumented omission.
+
+```typescript
+// ACCEPTABLE: Intentional fallback with logging
+try {
+  return await this.exchangeRateApi.getRate(currency);
+} catch (error) {
+  this.logger.warn({ currency, error }, 'Exchange rate API unavailable, using cached rate');
+  return await this.cache.get(`exchange-rate:${currency}`);
+}
+```
+
+### Default Values in Configuration
+
+Configuration defaults are not stubs when they represent the actual default behavior of the system. A default page size of 20, a default timeout of 30 seconds, or a default locale of 'en-US' is legitimate application behavior.
+
+---
+
+## Enforcement During Code Review
+
+When reviewing code for stub violations, check the following:
+
+1. **New functions**: Does every new function have a real implementation? Check return statements for hardcoded values.
+2. **New endpoints**: Does every new API endpoint call through to a real service? Trace the call from controller to service to data layer.
+3. **New components**: Does every new UI component receive data from props or hooks? Check for inline data arrays or objects.
+4. **Error handling**: Does every try/catch block handle the error? Search for empty catch bodies.
+5. **Comments**: Search for TODO, FIXME, HACK, and related keywords. If found, ask: is this a tracking comment (acceptable if linked to a ticket) or a replacement for actual implementation (unacceptable)?
+
+---
+
+## Interaction with TDD
+
+The anti-stub skill and the TDD skill reinforce each other:
+
+- **TDD prevents stubs** by requiring a test to fail before code is written. A test that demands real behavior will not pass with a stub (if the test is well-written).
+- **Anti-stub catches TDD gaps** by identifying cases where the test passed with a stub because the test's assertions were too weak.
+- **Together**: write a test that demands real behavior (TDD), implement the real behavior (anti-stub), verify that the test fails when the behavior is reverted to a stub (anti-stub validation).
+
+If a test passes when the production code returns `return []`, the test is insufficient. Either add assertions that check for specific expected data, or add additional test cases that vary the input and verify corresponding output variation. A function that always returns the same value regardless of input is, by definition, a stub.
+
+---
+
+## The Anti-Stub Mindset
+
+Stubs exist because of a well-intentioned impulse: "Let me get the structure in place and fill in the details later." The anti-stub discipline replaces this with: "Let me build only what I can build completely, right now."
+
+This means smaller increments, more focused pull requests, and fewer half-built features. It means a codebase where every function that exists actually works, every endpoint that responds actually does something, and every component that renders actually shows real data. The codebase becomes trustworthy — when something exists, it works.

package/plugin/skills/brainstorm/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: brainstorm
+description: Explore ideas before committing to a plan. Creative divergent thinking, then converge on a direction.
+version: 0.1.0
+---
+
+# /brainstorm — Creative Exploration
+
+Dispatch the **brainstormer** agent for pre-pipeline creative exploration.
+
+## Behavior
+
+**User provides a topic** (e.g., `/brainstorm multi-tenancy`):
+- Dispatch the brainstormer agent with the topic as the seed.
+- The brainstormer explores possibilities, challenges assumptions, and converges on a direction.
+
+**No topic provided** (bare `/brainstorm`):
+- Dispatch the brainstormer agent in open exploration mode.
+- The brainstormer asks what's on the user's mind.
+
+## Handoff to Forge Pipeline
+
+- The brainstormer produces a Brief document at `docs/plans/YYYY-MM-DD-{TITLE}/brief.md`.
+- When the user is ready to build, create a pipeline project with `mcp__dk-forge__create_project` and start the Strategist with the Brief summary as `initial_request`.
+- This handoff bridges creative exploration into the structured Forge pipeline.
+
+## Key Distinction
+
+- `/brainstorm` is standalone creative exploration — no pipeline engine interaction.
+- `/forge` is the structured pipeline entry point.
+- A brainstorm session naturally flows into `/forge` when the user decides to build.