@runecraft/grimoire 1.0.0

package/skills/spec-driven/references/context-limits.md

@@ -0,0 +1,31 @@
+# Context Limits
+
+## File Size Limits
+
+| File      | Max Tokens | ~Words | Warning At |
+| --------- | ---------- | ------ | ---------- |
+| spec.md   | 5,000      | 3,000  | 4,000      |
+| design.md | 8,000      | 4,800  | 6,400      |
+| tasks.md  | 10,000     | 6,000  | 8,000      |
+
+## Context Zones
+
+🟢 **Healthy** (<40k total): Silent
+🟡 **Moderate** (40-60k): Discrete footer note
+🔴 **Critical** (>60k): Active warning, suggest optimization
+
+## Monitoring
+
+Display context status in footer when >40k:
+
+```
+📊 Context: 52k tokens (moderate)
+  - tasks.md: 11k (ok)
+  - design.md: 6k (ok)
+  - Total: 52k / 200k (26%)
+```
+
+## Principles
+
+**Target:** <40k tokens loaded (20% of window)
+**Reserve:** 160k+ tokens for work, reasoning, outputs

package/skills/spec-driven/references/design.md

@@ -0,0 +1,199 @@
+# Design
+
+**Goal**: Define HOW to build it. Architecture, components, what to reuse.
+
+**Skip this phase when:** The change is straightforward — no architectural decisions, no new patterns, no component interactions to plan. For simple features, design happens inline during Execute.
+
+## Process
+
+### 1. Load Context
+
+Read `.specs/features/[feature]/spec.md` before designing. If `.specs/features/[feature]/context.md` exists, load it too — it contains implementation decisions that constrain the design (layout choices, behavior preferences, interaction patterns). Decisions marked as "Agent's Discretion" are yours to decide.
+
+**Mandatory: read `.specs/STATE.md` `## Decisions` now.** This MUST happen before any architectural choices are made. Every `active` `AD-NNN` entry is a project-level constraint this design must conform to. If a decision from a prior feature conflicts with what is best for this feature, you have two options — both require an explicit choice:
+
+1. **Conform** — Design within the active constraint.
+2. **Supersede** — Append a new `AD-NNN` entry to `.specs/STATE.md` `## Decisions` that supersedes the old one (set the old entry's `status` to `superseded by AD-NNN`) and document the reason. The new decision becomes the project standard going forward.
+
+Silently ignoring an active decision is not an option — it creates invisible inconsistency across features.
+
+**Also load confirmed lessons** relevant to this feature: `python3 scripts/lessons.py list --status confirmed` (filter with `--scope`/`--query`). These are past verification failures distilled into guidance — apply them while designing. Load only `confirmed`. Skip silently if no store or no code tool. See [lessons.md](lessons.md).
+
+### 1.5. Research (Optional but Recommended)
+
+If the feature involves unfamiliar technology, patterns, or integrations, research before designing. Document findings briefly in the design doc or as inline notes. This prevents incorrect assumptions from propagating into tasks.
+
+Follow the **Knowledge Verification Chain** (see SKILL.md) in strict order:
+
+```
+Codebase → Project docs → Context7 MCP → Web search → Flag as uncertain
+```
+
+**CRITICAL: NEVER assume or fabricate information.** If you cannot find an answer through the chain, explicitly say "I don't know" or "I couldn't find documentation for this". Inventing an API, a pattern, or a behavior that doesn't exist is far worse than admitting uncertainty. Wrong assumptions propagate through design → tasks → implementation and cause cascading failures.
+
+Good triggers for research: new libraries, unfamiliar APIs, performance-sensitive features, security-sensitive features, patterns you haven't used in this codebase before.
+
+**Concern flagging (MUST do while reading code):** While walking the codebase via the Knowledge Verification Chain, flag any concerns you encounter in the areas this feature touches. Capture each finding in the `## Risks & Concerns` section of `design.md`:
+
+- **Fragile code** — tight coupling, large functions, implicit state
+- **Tech debt** — hacks, workarounds, deprecated APIs
+- **Security risks** — unvalidated input, auth gaps, exposed secrets
+- **Performance bottlenecks** — N+1 queries, unbounded loops, missing indexes
+- **Test coverage gaps** — untested paths the feature depends on
+
+Every flagged concern MUST include a mitigation — how the design (or a follow-up task) addresses it.
+
+### 2. Define Architecture
+
+**Large/Complex only — approach exploration:** Before committing to a single architecture, present 2–3 viable approaches with trade-offs and a recommendation. Lead with the recommendation to avoid analysis paralysis. All approaches must deliver the same scoped thing (no alternative scopes). Confirm the chosen approach with the user before detailing components. Medium features: skip — design inline.
+
+Overview of how components interact. Use mermaid diagrams when helpful.
+
+### 3. Identify Code Reuse
+
+**CRITICAL**: What existing code can we leverage? This saves tokens and reduces errors.
+
+Flag any concerns found here per step 1.5 into `## Risks & Concerns`.
+
+### 4. Define Components and Interfaces
+
+Each component: Purpose, Location, Interfaces, Dependencies, What it reuses.
+
+### 5. Define Data Models
+
+If the feature involves data, define models before implementation.
+
+---
+
+## Template: `.specs/features/[feature]/design.md`
+
+````markdown
+# [Feature] Design
+
+**Spec**: `.specs/features/[feature]/spec.md`
+**Status**: Draft | Approved
+
+---
+
+## Architecture Overview
+
+[Brief description of the architecture approach]
+
+```mermaid
+graph TD
+    A[User Action] --> B[Component A]
+    B --> C[Service Layer]
+    C --> D[Data Store]
+    B --> E[Component B]
+```
+````
+
+---
+
+## Code Reuse Analysis
+
+### Existing Components to Leverage
+
+| Component            | Location            | How to Use                |
+| -------------------- | ------------------- | ------------------------- |
+| [Existing Component] | `src/path/to/file`  | [Extend/Import/Reference] |
+| [Existing Utility]   | `src/utils/file`    | [How it helps]            |
+| [Existing Pattern]   | `src/patterns/file` | [Apply same pattern]      |
+
+### Integration Points
+
+| System         | Integration Method                      |
+| -------------- | --------------------------------------- |
+| [Existing API] | [How new feature connects]              |
+| [Database]     | [How data connects to existing schemas] |
+
+---
+
+## Components
+
+### [Component Name]
+
+- **Purpose**: [What this component does - one sentence]
+- **Location**: `src/path/to/component/`
+- **Interfaces**:
+  - `methodName(param: Type): ReturnType` - [description]
+  - `methodName(param: Type): ReturnType` - [description]
+- **Dependencies**: [What it needs to function]
+- **Reuses**: [Existing code this builds upon]
+
+### [Component Name]
+
+- **Purpose**: [What this component does]
+- **Location**: `src/path/to/component/`
+- **Interfaces**:
+  - `methodName(param: Type): ReturnType`
+- **Dependencies**: [Dependencies]
+- **Reuses**: [Existing code]
+
+---
+
+## Data Models (if applicable)
+
+### [Model Name]
+
+```typescript
+interface ModelName {
+  id: string
+  field1: string
+  field2: number
+  createdAt: Date
+}
+```
+
+**Relationships**: [How this relates to other models]
+
+### [Model Name]
+
+```typescript
+interface AnotherModel {
+  id: string
+  // ...
+}
+```
+
+---
+
+## Error Handling Strategy
+
+| Error Scenario | Handling      | User Impact      |
+| -------------- | ------------- | ---------------- |
+| [Scenario 1]   | [How handled] | [What user sees] |
+| [Scenario 2]   | [How handled] | [What user sees] |
+
+---
+
+## Risks & Concerns
+
+| Concern | Location (file:line) | Impact | Mitigation |
+| ------- | -------------------- | ------ | ---------- |
+| [Fragile code / tech debt / security / perf / test gap] | `src/path/file.ts:42` | [What breaks or degrades] | [How the design or a follow-up task addresses it] |
+
+> None found — is a valid entry.
+
+---
+
+## Tech Decisions (only non-obvious ones)
+
+| Decision          | Choice          | Rationale     |
+| ----------------- | --------------- | ------------- |
+| [What we decided] | [What we chose] | [Why - brief] |
+
+> **Project-level decisions:** If a decision here sets a convention, pattern, or constraint that future features must follow, append it to `.specs/STATE.md` `## Decisions` as the next `AD-NNN` entry (see [memory.md](memory.md)). Feature-local decisions stay only in this table.
+
+---
+
+## Tips
+
+- **Load context first** — If context.md exists, decisions there are locked
+- **Research when uncertain** — 5 minutes of research prevents hours of rework
+- **Reuse is king** — Every component should reference existing patterns
+- **Interfaces first** — Define contracts before implementation
+- **Keep it visual** — Diagrams save 1000 words
+- **Small components** — If component does 3+ things, split it
+- **Flag concerns inline** — Risks found during research go in Risks & Concerns with a mitigation
+- **Confirm before Tasks** — User approves design before breaking into tasks

package/skills/spec-driven/references/discuss.md

@@ -0,0 +1,136 @@
+# Specify: Discuss Gray Areas
+
+**Goal:** Capture HOW the user envisions the feature when the spec has ambiguous areas. This is NOT a separate phase — it's triggered within Specify when the agent detects gray areas that need user input.
+
+**Trigger:** Automatically when gray areas are detected during spec creation, or explicitly via "discuss feature", "how should this work?", "capture context"
+
+**When to trigger (auto-detect):** The spec contains user-facing behavior that could go multiple ways AND the user hasn't expressed a preference. If the spec is clear and unambiguous, skip this entirely.
+
+**When NOT to trigger:** Genuinely trivial features — a pure read endpoint, a config tweak, features with no [implicit-requirement dimensions](specify.md#implicit-requirement-dimensions) present (no persistence/state, external calls, auth, payments, concurrency, or state transitions). When any dimension is present, trigger discuss.
+
+## Why This Phase Exists
+
+Specifications capture WHAT to build. Design captures the architecture. But neither captures the user's vision for ambiguous areas — layout preferences, interaction patterns, error handling style, content tone. Without this, the agent guesses. With this, the agent builds what the user actually imagined.
+
+The output — `context.md` — feeds directly into Design and Tasks:
+
+- **Design reads it** to know what decisions are locked vs. flexible
+- **Tasks reads it** to include specific behaviors in task definitions
+
+## Process
+
+### 1. Analyze the Feature
+
+Read `.specs/features/[feature]/spec.md` and identify the domain:
+
+| Domain                         | Gray areas to explore                                         |
+| ------------------------------ | ------------------------------------------------------------- |
+| Something users **SEE**        | Layout, density, interactions, empty states, visual hierarchy |
+| Something users **CALL** (API) | Response format, errors, auth, versioning, rate limiting      |
+| Something users **RUN** (CLI)  | Output format, flags, modes, error handling, verbosity        |
+| Something users **READ**       | Structure, tone, depth, flow, navigation                      |
+| Something being **ORGANIZED**  | Grouping criteria, naming, duplicates, exceptions             |
+| Something with **backend / state / contract** | Failure & partial-failure states, idempotency/retry/dedup, auth boundaries & rate limits, data lifecycle/expiry, concurrency/ordering — see [implicit-requirement dimensions](specify.md#implicit-requirement-dimensions) |
+
+Generate 3-4 **feature-specific** gray areas. Not generic categories, but concrete decisions for THIS feature.
+
+### 2. Present Gray Areas
+
+Present the feature boundary (from spec.md) and the gray areas to the user. Let them choose which to discuss. Do NOT include a "skip all" option — the user invoked this phase to discuss.
+
+Any gray area the user **declines** to discuss, or that goes undiscussed, is written to the spec's **Assumptions & Open Questions** section (agent's chosen default + rationale) — never silently dropped. This ensures the spec's closure gate can pass: every gray area is either resolved through discussion or recorded as a signed-off assumption.
+
+### 3. Deep-Dive Each Area
+
+For each selected area:
+
+1. Ask 3-4 concrete questions with specific options (not vague categories)
+2. After the questions, check: "More about [area], or move on?"
+3. If more → ask 3-4 more, check again
+4. After all areas → "Ready to create context?"
+
+**Question design:**
+
+- Options should be concrete ("Card layout" not "Option A")
+- Each answer should inform the next question
+- Include "You decide" as an option when reasonable — captures agent discretion
+
+### 4. Scope Guardrail (CRITICAL)
+
+The feature boundary from spec.md is **fixed**. Discussion clarifies HOW to implement, never WHETHER to add new capabilities.
+
+**Allowed:** "How should posts be displayed?" (clarifying ambiguity)
+**Not allowed:** "Should we also add comments?" (new capability)
+
+When user suggests scope creep: "That sounds like a separate feature. I'll note it in Deferred Ideas. Back to [current area]."
+
+### 5. Write context.md
+
+---
+
+## Template: `.specs/features/[feature]/context.md`
+
+```markdown
+# [Feature] Context
+
+**Gathered:** [date]
+**Spec:** `.specs/features/[feature]/spec.md`
+**Status:** Ready for design
+
+---
+
+## Feature Boundary
+
+[Clear statement of what this feature delivers — the scope anchor from spec.md]
+
+---
+
+## Implementation Decisions
+
+### [Area 1 that was discussed]
+
+- [Specific decision made]
+- [Another decision if applicable]
+
+### [Area 2 that was discussed]
+
+- [Specific decision made]
+
+### [Area 3 that was discussed]
+
+- [Specific decision made]
+
+### Agent's Discretion
+
+[Areas where user explicitly said "you decide" — agent has flexibility here during design/implementation]
+
+### Declined / Undiscussed Gray Areas → Assumptions
+
+[Gray areas the user declined to discuss or that were not covered. Each entry is written to the spec's Assumptions & Open Questions section with the agent's chosen default and rationale — not left silently unresolved.]
+
+---
+
+## Specific References
+
+[Any "I want it like X" moments, product references, specific behaviors, interaction patterns mentioned during discussion]
+
+[If none: "No specific requirements — open to standard approaches"]
+
+---
+
+## Deferred Ideas
+
+[Ideas that came up during discussion but belong in other features/phases. Captured here so they're not lost, but explicitly out of scope]
+
+[If none: "None — discussion stayed within feature scope"]
+```
+
+---
+
+## Tips
+
+- **Decisions, not vision** — "Card-based layout with subtle shadows" is a decision. "Should feel modern" is not.
+- **Scope is sacred** — Deferred Ideas captures scope creep without losing ideas
+- **User = visionary, Agent = builder** — Ask about how they imagine it, not about technical implementation
+- **Don't ask about:** Technical architecture, performance, implementation details — that's Design's job
+- **Confirm before Design** — User approves context.md before moving to design phase