forge-orkes 0.1.0

package/template/.claude/skills/discussing/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: discussing
+description: "Use when you need to talk through approach, trade-offs, or concerns before committing to action. Trigger between researching and planning (pre-plan discussion), or invoke on any existing phase/plan to revisit decisions. This skill facilitates conversation — it doesn't write plans or code."
+---
+
+# Discussing
+
+Facilitate a structured conversation about approach, trade-offs, and decisions. This skill produces clarity, not artifacts.
+
+## When to Invoke
+
+### Pre-Planning (Default Position in Workflow)
+After `researching`, before `planning`. The agent has findings — now help the user decide what to do with them before locking anything into a plan.
+
+### Post-Planning (On-Demand)
+User says "discuss Phase 2" or "let's talk through plan 03" or "I want to rethink the auth approach." The plan exists but the user wants to revisit it before (or instead of) executing.
+
+### Mid-Workflow
+User feels uncertain, wants to step back, or says things like "wait," "I'm not sure about this," "what are the alternatives?" Route here from any skill — discussion is always available.
+
+## What This Skill Does NOT Do
+
+- **Does not write plans.** That's the `planning` skill.
+- **Does not write code.** That's the `executing` skill.
+- **Does not modify `.forge/` files.** Discussion produces decisions — the next skill writes them down.
+- **Does not require a phase or plan to exist.** You can discuss a vague idea.
+
+The only output is the conversation itself and, at the end, a summary of decisions made that the next skill should honor.
+
+## Pre-Planning Discussion
+
+When entering from `researching` with findings in hand:
+
+### Step 1: Present the Landscape
+
+Summarize what research found, structured around decisions the user needs to make — not a data dump.
+
+*"Based on what I found, here are the key decisions before we plan:"*
+
+For each decision point:
+- **What needs deciding** — the question, stated plainly
+- **Options** — 2-3 realistic approaches (not exhaustive lists)
+- **Trade-offs** — what you gain and what you lose with each
+- **Recommendation** — if you have one, say so and say why. If you don't, say that too.
+
+Keep it conversational. Don't present a 20-item matrix. Surface the 3-5 decisions that actually matter for this work.
+
+### Step 2: Facilitate, Don't Dictate
+
+Your role is to help the user think, not to push them toward your preference.
+
+Good facilitation patterns:
+- *"The main tension here is between X and Y. Which matters more for your project?"*
+- *"Option A is simpler now but harder to change later. Option B is more work upfront but more flexible. What's your timeline pressure like?"*
+- *"I'd lean toward X because [reason], but Y makes sense if [condition]. What's your read?"*
+- *"You mentioned [earlier decision] — that makes Option B a more natural fit. Does that match your thinking?"*
+
+Bad facilitation patterns:
+- Presenting options without trade-offs (just a list)
+- Asking "what do you think?" without giving the user something to react to
+- Overwhelming with edge cases before the main path is clear
+- Treating every decision as equally important
+
+### Step 3: Probe for Hidden Constraints
+
+Research often misses things the user knows but hasn't mentioned. Ask about:
+- **Timeline pressure** — does this need to ship by a date?
+- **Audience/users** — who actually uses this? (affects complexity trade-offs)
+- **Future direction** — is this a throwaway or the foundation for more?
+- **Past experience** — have they tried something similar before? What went wrong?
+- **Strong preferences** — anything they definitely want or definitely don't want?
+
+One or two questions at a time. Don't interrogate.
+
+### Step 4: Functionality Distillation
+
+This is the heart of the discussing skill. Walk through each major feature or requirement and ask targeted questions that force clarity about *how the system should actually behave*. The goal is to surface the implicit assumptions and edge cases that the user hasn't articulated yet — but will need answers to during implementation.
+
+**For each feature/requirement, work through these question layers:**
+
+**Layer 1: The Happy Path**
+What does success look like from the user's perspective? Walk through the ideal scenario step by step.
+- *"When a user [triggers this feature], what should they see/experience first?"*
+- *"Walk me through what happens next — what's the sequence?"*
+- *"When it's done, what confirms to the user that it worked?"*
+
+**Layer 2: Boundaries and Rules**
+What are the constraints? What's allowed and what isn't?
+- *"Who can do this? Everyone, or only certain roles/states?"*
+- *"Is there a limit — how many, how often, how large?"*
+- *"What triggers this — user action, scheduled event, or reaction to something else?"*
+- *"Does this depend on anything else being true first?"*
+
+**Layer 3: When Things Go Wrong**
+What happens when the expected path breaks?
+- *"What if [the input is invalid / the service is down / the user cancels halfway]?"*
+- *"Should the system retry, fail gracefully, or alert someone?"*
+- *"If two users do this simultaneously, what should happen?"*
+- *"What's the worst thing that could happen if this feature has a bug?"*
+
+**Layer 4: Interactions and Side Effects**
+How does this feature affect the rest of the system?
+- *"When this happens, does anything else need to update?"*
+- *"Should other users be notified? How?"*
+- *"Does this affect [related feature the research uncovered]? How?"*
+- *"Can this be undone? Should it be?"*
+
+**Layer 5: Evolution**
+How might this change over time?
+- *"Is this a v1 that you expect to expand later, or is this the final shape?"*
+- *"If you had to cut scope, which parts of this are essential vs. nice-to-have?"*
+- *"What's the most likely thing you'd want to change about this in 3 months?"*
+
+**How to use the layers:**
+
+Don't mechanically walk through all 5 layers for every requirement — that would take hours. Instead:
+
+- **Always do Layer 1** — if the happy path isn't clear, nothing else matters.
+- **Do Layer 2 for anything with rules** — permissions, limits, validations, workflows.
+- **Do Layer 3 for anything critical** — payments, data mutations, auth, external integrations.
+- **Do Layer 4 when features interact** — if research found shared state or dependencies between features.
+- **Do Layer 5 when scope feels uncertain** — if the user seems unsure how much to build now.
+
+Ask 2-3 questions at a time, let the user respond, then go deeper where their answers reveal uncertainty. The conversation should feel like a collaborative design session, not an interrogation.
+
+**What you're listening for:**
+
+- **Contradictions** — "It should be simple" but also "it needs to handle 12 different states." Surface these gently.
+- **Vague handwaving** — "It should just work normally." Push for specifics: *"What does 'normally' mean here? Can you describe one concrete example?"*
+- **Assumed knowledge** — "Like how Stripe does it." Confirm you share the same mental model: *"I want to make sure I understand — you mean [specific behavior], right?"*
+- **Energy shifts** — When the user gets excited about a detail, that's signal. When they get bored or dismissive, that's also signal. The things they care about should get more attention in the plan.
+
+### Step 5: Converge on Decisions
+
+When the conversation has covered the key points, summarize what's been decided:
+
+*"Here's where I think we've landed:*
+- *[Decision 1]: [what was decided and why]*
+- *[Decision 2]: [what was decided and why]*
+- *[Open question]: [what's still unresolved and how to handle it]*
+
+*Does this match your understanding? If so, I'll carry these into planning."*
+
+These decisions flow into `context.md` as **Locked Decisions** when the `planning` skill runs next.
+
+## Post-Planning Discussion
+
+When invoked on an existing phase or plan:
+
+### Step 1: Load Context
+
+Read the relevant files:
+- The plan being discussed (`.forge/phases/{N}-{name}/plan-{NN}.md`)
+- Requirements it's based on (`.forge/requirements.yml`)
+- Locked decisions (`.forge/context.md`)
+- Constitution (`.forge/constitution.md`)
+
+### Step 2: Present the Plan in Plain Language
+
+Don't just recite the plan back. Translate it into what it means:
+
+*"Phase 2 has 3 plans with 8 tasks total. Here's what it actually does:*
+
+*Plan 01 builds [feature A] — it creates [these things] and wires them to [these things]. The main risk is [risk]. Estimated at [time].*
+
+*Plan 02 builds [feature B] — [same pattern].*
+
+*The key assumption is [assumption]. If that's wrong, plans 02 and 03 would need rework."*
+
+### Step 3: Surface What's Worth Discussing
+
+Don't wait for the user to spot issues. Proactively surface:
+
+- **Assumptions you're not confident about** — "Plan 01 assumes the API returns paginated results. I didn't verify this."
+- **Decisions that could go either way** — "I split this into 3 plans for parallelism, but you could also do it as 2 larger plans if you prefer fewer context switches."
+- **Risks the plan doesn't address** — "There's no fallback if the external API is slow. Worth adding, or accept the risk?"
+- **Scope questions** — "Plan 03 includes admin-only features. Ship those in v1, or defer?"
+
+### Step 4: Drill into Functionality
+
+Use the same **Functionality Distillation** question layers from Pre-Planning Step 4, but now grounded in the concrete plan. Instead of asking about abstract requirements, ask about the specific tasks and how they'll behave:
+
+- *"Task 2 creates the notification service. When a notification fails to send, should the system retry or just log it?"*
+- *"Plan 01 wires the dashboard to the API. Should the dashboard poll for updates, or should changes push in real-time?"*
+- *"The plan has user roles as a task, but the requirements don't specify what each role can do. Can we walk through the permissions?"*
+
+This is where post-planning discussion earns its keep — the plan makes the feature concrete enough to ask questions that were impossible during pre-planning.
+
+### Step 5: Discuss and Revise Direction
+
+The user may want to:
+- **Change approach** — "Let's use WebSockets instead of polling." → Note this. Planning skill will rebuild the affected plans.
+- **Adjust scope** — "Defer the admin features." → Note this for deferred items.
+- **Reorder priorities** — "Do the dashboard before the settings page." → Note the new wave order.
+- **Ask questions** — "What happens if we skip the caching layer?" → Discuss implications honestly.
+- **Approve as-is** — "Looks good, proceed." → Move to executing.
+
+### Step 6: Summarize Changes
+
+If the discussion produced changes to the plan direction:
+
+*"Based on our discussion:*
+- *[Change 1]: [what changed and why]*
+- *[Change 2]: [what changed and why]*
+- *[Unchanged]: [what stays the same]*
+
+*Next step: I'll update the plans to reflect this. Want me to proceed with re-planning, or is there more to discuss?"*
+
+If re-planning is needed, route back to the `planning` skill with the discussion summary as input. The planning skill will update plans, requirements, and context.md accordingly.
+
+## Facilitation Principles
+
+1. **Lead with the interesting question, not the obvious one.** "Should we use React?" is boring if the project already uses React. "Should the dashboard update in real-time or on refresh?" is the real decision.
+
+2. **Name the trade-off, don't hide it.** Every decision has a cost. Saying "Option A is better" without saying "but it takes 2x longer" is dishonest facilitation.
+
+3. **Reference what the user has already told you.** Good facilitators remember. If the user said "I want this done by Friday" three messages ago, factor that into every recommendation.
+
+4. **Know when to stop discussing.** If the user is clear and confident, don't manufacture uncertainty. Some discussions take 2 minutes. That's fine.
+
+5. **Separate "must decide now" from "can decide later."** Not every question needs an answer before planning starts. Flag what can be deferred and what can't.
+
+## Anti-Patterns
+
+- **Analysis paralysis** — discussing for 30 minutes what could be decided in 5. If the user is going in circles, name it: "I think we have enough to move forward. We can revisit after seeing the first implementation."
+- **False facilitation** — asking questions you already know the answer to. If the research clearly points one way, say so.
+- **Premature convergence** — locking decisions before the user has had a chance to think. Don't rush the summary.
+- **Scope creep via discussion** — "While we're at it, should we also..." Keep discussion focused on the work at hand.
+- **Discussion as procrastination** — if the user keeps wanting to discuss but never approves a plan, gently surface the pattern.

package/template/.claude/skills/executing/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: executing
+description: "Use when building: writing code, creating files, running tests. Trigger when you have an approved plan and need to implement it. This skill enforces atomic commits, deviation rules, context engineering, and TDD when applicable."
+---
+
+# Executing
+
+Build to plan with atomic commits, smart deviation handling, and context engineering.
+
+## Pre-Execution Checklist
+
+Before writing any code:
+- [ ] Plan exists (`.forge/phases/{N}-{name}/plan-{NN}.md`)
+- [ ] Context.md reviewed (locked decisions noted)
+- [ ] Constitution.md gates satisfied (from planning phase)
+- [ ] Current milestone state (`.forge/state/milestone-{id}.yml`) updated to `status: executing`
+
+## Deviation Rules
+
+When you encounter issues while building, follow this decision tree:
+
+### Rule 4 Check First (Architectural)
+Does the issue require a new database table, service layer, major schema change, library swap, or infrastructure change?
+- **YES** → **STOP.** Create checkpoint. Document: what you found, proposed change, why needed, impact, alternatives. Wait for user decision.
+- **NO** → Continue to Rules 1-3.
+
+### Rule 1: Auto-Fix Bugs
+Issue is a simple bug blocking the current task (broken behavior, wrong output, error).
+→ Fix inline. Add test if applicable. Document in summary: "Rule 1: Fixed [bug] because [reason]."
+
+### Rule 2: Auto-Add Critical Functionality
+Missing error handling, input validation, null checks, auth checks, CSRF protection, rate limiting, logging.
+→ Add it. Document in summary: "Rule 2: Added [functionality] because [reason]."
+
+### Rule 3: Auto-Fix Blocking Infrastructure
+Missing dependency, wrong types, broken imports, env var misconfiguration, build config issue.
+→ Fix it. Document in summary: "Rule 3: Fixed [issue] because [reason]."
+
+### 3-Strike Limit
+After 3 auto-fix attempts on a single task → STOP fixing. Document remaining issues in summary. Move to next task.
+
+### Scope Boundary
+Only fix issues DIRECTLY caused by the current task. Pre-existing warnings, tech debt, unrelated bugs → log to `.forge/deferred-issues.md`, don't fix.
+
+## Task Execution Flow
+
+For each task in the plan:
+
+1. **Read** the task XML (name, files, action, verify, done)
+2. **Check** context.md — does this task touch a locked decision? Honor it exactly.
+3. **Implement** following the action instructions
+4. **Verify** using the verify step (run tests, inspect output)
+5. **Confirm** done criteria are met
+6. **Commit** atomically
+
+## TDD Flow (When task type="tdd")
+
+### With Test Spec (from planning Step 7)
+When the task has a `<spec>` field, test specs already exist:
+1. **Copy spec to test location:** Move from `.forge/phases/` to the project's test directory
+2. **RED:** Remove `skip` markers from the first test. Confirm it fails. Commit: `test({scope}): activate spec tests for {feature}`
+3. **GREEN:** Write minimal code to make it pass. Repeat for each test in the spec.
+4. **REFACTOR:** Clean up. Commit: `feat({scope}): implement {feature}`
+
+### Without Test Spec (standard TDD)
+1. **RED:** Write failing tests first. Commit: `test({scope}): add failing tests for {feature}`
+2. **GREEN:** Write minimal code to pass tests. Commit: `feat({scope}): implement {feature}`
+3. **REFACTOR:** Clean up if needed. Commit: `refactor({scope}): clean up {feature}`
+
+## Atomic Commit Protocol
+
+After each task completes:
+
+1. Stage only task-related files individually: `git add src/specific/file.ts`
+2. **NEVER** use `git add .` or `git add -A`
+3. Commit with format: `{type}({phase}-{plan}): {description}`
+4. Include bullet-point body listing key changes
+5. Verify commit was created: `git log -1`
+
+```
+feat(auth-01): implement JWT-based login
+
+- Add LoginForm component using PrimeReact Dialog and InputText
+- Create useAuth hook with token refresh logic
+- Add /api/auth/login endpoint with bcrypt verification
+- Include integration test for login flow
+```
+
+## Context Engineering
+
+### When to Spawn Fresh Agent
+- Task touches 20+ files
+- Task involves complex subsystem with deep dependency tree
+- Current context exceeds ~60% utilization
+- Switching between unrelated subsystems
+
+### How to Spawn
+Use the Task tool with a focused prompt:
+- Include only relevant plan details
+- Reference specific files to modify
+- Pass locked decisions from context.md
+- Set clear success criteria
+
+### Size Monitoring
+After each task, mentally assess context usage:
+- Under 40%: continue normally
+- 40-60%: consider fresh agent for next task
+- Over 60%: spawn fresh agent
+
+## Execution Summary
+
+After completing all tasks in a plan, create a summary:
+
+```markdown
+# Execution Summary: Phase {N}, Plan {NN}
+
+## Completed Tasks
+1. [Task name] — [one-line result]
+2. [Task name] — [one-line result]
+
+## Deviations
+- Rule 1: Fixed [bug] in [file] because [reason]
+- Rule 2: Added [functionality] to [file] because [reason]
+
+## Commits
+- abc1234: feat(auth-01): implement login form
+- def5678: test(auth-01): add login integration tests
+
+## Files Modified
+- src/components/Login.tsx (created)
+- src/hooks/useAuth.ts (created)
+- src/api/auth/login.ts (created)
+
+## Notes
+[Anything the verifier should know]
+```
+
+## State Updates
+
+After plan execution:
+1. Update `.forge/state/milestone-{id}.yml` — advance plan counter, update progress
+2. Record deviations in the milestone state file
+3. Update `.forge/state/index.yml` — set milestone `last_updated` timestamp
+4. If all plans in phase complete → transition to `verifying`
+
+## Desire Path Signals
+
+While executing, watch for and log these patterns in `.forge/state/index.yml → desire_paths` (desire paths are global, not per-milestone):
+
+- **Repeated deviations**: If you apply the same deviation rule for the same reason more than once (e.g., adding null checks in every API handler), log it as a `deviation_pattern`. Don't just record each deviation individually — notice when they form a pattern.
+- **User corrections**: If the user corrects your output and the correction matches something they've corrected before (e.g., "use the Card component, not a div"), log it as a `user_correction` and increment the count.
+- **Agent struggles**: If you need multiple attempts to get something right, or the user has to guide you through it, log the task type as an `agent_struggle`.
+
+This takes seconds per signal. Don't skip it — this data drives framework evolution.