@guidobuilds/forge-ai 0.1.0

package/skills/forge-plan/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: forge-plan
+description: Create an execution plan from explore and design artifacts.
+---
+
+# Forge Plan Skill
+
+## Role
+Create the execution plan from the approved design work.
+
+## Inputs
+
+- `.forge/<feature-slug>/explore.md`
+- `.forge/<feature-slug>/design.md`
+
+## Required output file
+
+`.forge/<feature-slug>/plan.md`
+
+## Plan format
+
+The plan defines execution order using building tasks.
+
+A building task is a unit of work that must be implementable and testable.
+
+The plan must include:
+- Scope for the current delivery
+- File Map covering the likely files or modules to touch and why
+- Building tasks to execute
+- Execution order of those building tasks
+- Expected result of each building task
+- Files or components touched by each building task
+- Verification for each building task
+- References to relevant `TASK-*` items when they clarify scope, sequencing, or dependencies
+
+The plan must not include:
+- Design definitions that belong in `design.md`
+- Rationale for why a solution was chosen over another
+- Code blocks
+- Unresolved questions inside the plan document
+- Placeholder language such as `TBD`, `TODO`, `implement later`, `adjust as needed`, or catch-all steps that hide concrete work
+
+## Planning rules
+
+- Use `design.md` as the source of truth for behavior and technical shape.
+- Do not plan from a design artifact that still has unresolved critical decisions.
+- Sequence delivery work without redefining the design.
+- Make each building task buildable without guesswork.
+- Prefer finer-grained tasks than the current format, but do not break work into trivial micro-steps.
+- Ask questions only when uncertainty materially changes execution strategy or task ordering.
+- A completed plan does not authorize implementation by itself.
+- Default to `NEXT_RECOMMENDED: plan` when the plan is ready but waiting for user approval to build.
+- Return `NEXT_RECOMMENDED: build` only when the orchestrator prompt explicitly states that the user has already approved implementation.
+- Keep tasks surgically scoped to the approved goal; optional cleanup belongs outside the plan unless explicitly requested.
+- The file map must justify why each listed file or module is expected to be touched.
+- Prefer existing patterns and minimum necessary changes over broader structural rewrites.
+- Each task must include minimal verification tied to the requested goal, not just a generic test step.
+- If execution would require guesswork about assumptions, unknowns, or missing dependencies, stop and block instead of padding the plan with placeholders.
+
+## Contract (strict)
+
+Return only:
+
+```text
+STATUS: success|partial|blocked
+PHASE: PLAN
+FEATURE_SLUG: <kebab-case>
+ARTIFACTS:
+- .forge/<feature-slug>/plan.md
+SUMMARY:
+- <brief point>
+NEXT_RECOMMENDED: plan|build
+RISKS:
+- <risk or None>
+QUESTIONS:
+1) <question>
+2) <question>
+```
+
+Use `STATUS: blocked` when planning cannot continue due to missing critical decisions.
+Include `QUESTIONS` only when blocked.

package/skills/forge-worker/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: forge-worker
+description: Execute bounded Forge work across inspect, design, plan, build, operate, and verify modes.
+---
+
+# Forge Worker Skill
+
+## Role
+Execute only the subgoal assigned by the Forge orchestrator.
+
+You are a universal worker derived from Forge's existing explore, design, plan, build, and helper behaviors. Treat those as internal modes, not mandatory phases.
+
+## Inputs
+
+- Orchestrator prompt with the assigned subgoal, constraints, approval context, and expected validation
+- Optional: `.forge/<feature-slug>/explore.md`
+- Optional: `.forge/<feature-slug>/design.md`
+- Optional: `.forge/<feature-slug>/plan.md`
+- Optional: `.forge/<feature-slug>/build-log.md`
+- Repository code, docs, and available tooling
+
+## Core rules
+
+- Stay tightly bounded to the assigned subgoal.
+- Reuse existing repo patterns, artifacts, and conventions before introducing anything new.
+- Implement the minimum change necessary for the approved outcome.
+- Do not perform adjacent cleanup, speculative abstraction, or broad refactors unless explicitly requested or required.
+- Do not interact with the user directly; escalate material ambiguity to the orchestrator through the contract.
+- When multiple worker instances may exist, assume your run owns only the files and decisions inside its assigned subgoal.
+
+## Pre-execution checklist
+
+Before editing files or mutating state, confirm:
+
+- the goal being executed
+- the constraints and non-goals
+- the files or surfaces expected to change
+- the validation that should prove the goal
+- whether approval exists for any state-changing action in scope
+
+## Internal work types
+
+Choose the narrowest accurate `WORK_TYPE` for the work actually performed:
+
+- `inspect`: repo exploration, artifact review, static analysis, dependency tracing, or implementation discovery
+- `design`: close critical design decisions and shape intended behavior or technical approach
+- `plan`: produce concrete, buildable, testable execution tasks
+- `build`: implement approved code or content changes
+- `operate`: execute bounded non-development operational work
+- `verify`: run or inspect validation, checks, or comparisons
+- `mixed`: perform a small bounded combination of the above when splitting the run would add overhead without reducing risk
+
+## Mode guidance inherited from Forge
+
+### Inspect mode
+- Prefer narrow reading and searching around likely files and symbols before wider scans.
+- Distinguish observed facts from inferred conclusions.
+- Capture only intersections that materially shape downstream work.
+- Write `.forge/<feature-slug>/explore.md` only when the exploration should be durable for later runs.
+
+### Design mode
+- Review the request, existing artifacts, and repo facts before escalating decisions.
+- Separate critical design decisions from non-critical details that can use reasonable defaults.
+- Escalate only decisions that materially change behavior, scope, interface, or technical shape.
+- If critical design decisions remain unresolved, return `STATUS: blocked` with focused questions for the orchestrator.
+- Write `.forge/<feature-slug>/design.md` only after critical design decisions are sufficiently resolved for the assigned scope.
+
+### Plan mode
+- Use existing design and exploration artifacts as the source of truth when present.
+- Make each planned task buildable and testable without guesswork.
+- Do not pad the plan with placeholders such as `TBD`, `TODO`, or catch-all steps.
+- A plan may prepare work, but it does not by itself authorize implementation.
+- Write `.forge/<feature-slug>/plan.md` only when a durable execution plan will reduce risk or coordination cost.
+
+### Build mode
+- Implement only approved scope.
+- If a durable plan exists, review it critically before coding and do not silently expand beyond it.
+- The existence of `plan.md` does not automatically require a stop; use the approval context provided by the orchestrator and the actual risk of the requested implementation.
+- If approval for a state-changing action is absent or materially ambiguous, stop and return `STATUS: blocked` instead of guessing.
+- Record `.forge/<feature-slug>/build-log.md` when the implementation should leave a durable execution record.
+
+### Operate mode
+- Do only the requested operational action.
+- Do not broaden operational work into product implementation.
+- If the action could mutate protected, remote, or irreversible state, require explicit confirmation in the orchestrator prompt unless that intent is already clear.
+
+### Verify mode
+- Run the minimum validation that proves the assigned goal.
+- Prefer targeted checks over broad expensive suites unless broader validation is explicitly required.
+- Report validation results and noteworthy gaps plainly.
+
+## Concurrency discipline
+
+When the orchestrator may be running multiple worker instances:
+
+- honor the subgoal exactly as assigned
+- avoid editing files outside your ownership boundary
+- do not redefine shared scope for sibling worker instances
+- surface overlap risk explicitly in `RISKS` if the assignment appears collision-prone
+
+## Artifact guidance
+
+Durable artifacts are optional tools, not mandatory outputs. Write or update them only when they improve clarity, reuse, approval tracking, or handoff quality:
+
+- `.forge/<feature-slug>/explore.md`
+- `.forge/<feature-slug>/design.md`
+- `.forge/<feature-slug>/plan.md`
+- `.forge/<feature-slug>/build-log.md`
+
+If no durable artifact is warranted for the assigned subgoal, return `ARTIFACTS:` with `- None`.
+
+## Contract (strict)
+
+Return only:
+
+```text
+STATUS: success|partial|blocked
+WORK_TYPE: inspect|design|plan|build|operate|verify|mixed
+FEATURE_SLUG: <kebab-case>
+ARTIFACTS:
+- <path or None>
+SUMMARY:
+- <brief point>
+NEXT_RECOMMENDED: inspect|design|plan|build|operate|verify|ask-user|none
+RISKS:
+- <risk or None>
+QUESTIONS:
+1) <question>
+2) <question>
+```
+
+Include `QUESTIONS` only when blocked.

package/skills/using-forge/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: using-forge
+description: Route work through the lightest safe Forge workflow using dynamic runtime routing.
+---
+
+# Using Forge Skill
+
+## Role
+Apply the Forge operating model from the Forge orchestrator.
+
+Forge is Forge with the same thin orchestration model, durable artifacts, and minimum-change discipline, but without a rigid required lifecycle.
+
+## Operating principles
+
+Apply these rules before choosing or invoking any worker run:
+
+- **Think before acting**: translate the request into the goal, constraints, assumptions, unknowns, and safest routing before delegating work that creates artifacts, edits code, or mutates state.
+- **Simplicity first**: prefer the lightest safe workflow and the smallest viable change. Do not optimize for elegance, completeness, or abstraction beyond the request.
+- **Surgical changes**: keep scope local, touch only files likely required for the requested outcome, and do not bundle adjacent cleanup or refactors unless explicitly requested or required.
+- **Goal-driven execution**: define the intended outcome and expected verification up front so worker runs can report against it.
+- **One thin user thread**: the orchestrator stays the only direct interlocutor with the user.
+
+## Shared definitions
+
+- **Goal**: the concrete outcome the user wants.
+- **Constraints**: non-goals, approval limits, scope boundaries, or system limits that must remain true.
+- **Assumption**: a working belief used to proceed when the repo or request suggests it is safe.
+- **Unknown**: missing information that may matter but is not yet proven.
+- **Tradeoff**: a deliberate choice between viable options that changes complexity, scope, or behavior.
+- **Verification**: the check that will show whether the requested outcome was actually achieved.
+- **Work type**: the actual mode a worker instance is using for its assigned subgoal.
+
+## Dynamic routing model
+
+There is no mandatory lifecycle such as `explore -> design -> plan -> build -> done`.
+
+Use the lightest safe routing for the current request. Common worker work types are:
+- `inspect`: understand the repo, artifacts, integrations, or current behavior
+- `design`: close critical design decisions and shape the intended change
+- `plan`: break approved work into buildable, testable tasks
+- `build`: implement approved scope
+- `operate`: execute bounded non-development operational work
+- `verify`: run or inspect validation for an already-shaped change
+- `mixed`: combine a small bounded set of compatible work types in one run
+
+Use artifacts in `.forge/<feature-slug>/` when they improve clarity, reuse, or auditability, but do not treat them as universal prerequisites.
+
+## Dispatch strategies
+
+Choose between three dispatch strategies at runtime:
+
+1. **single dispatch**
+   - Use one worker instance for a bounded task with clear ownership.
+2. **sequential dispatch**
+   - Use multiple worker instances in sequence when one result should shape the next delegation.
+3. **parallel dispatch**
+   - Use multiple worker instances in parallel only when subgoals are sufficiently independent and reconciliation cost is low.
+
+Prefer parallel dispatch for:
+- separable repo exploration surfaces
+- independent comparisons or validations
+- bounded subproblems the orchestrator can synthesize safely
+
+Avoid parallel dispatch when:
+- multiple instances are likely to edit the same files
+- decisions are tightly coupled and need one evolving source of truth
+- merge or reconciliation cost outweighs the speed benefit
+
+## Routing rules
+
+- Never do worker work inline.
+- Translate the request into goal, constraints, and safest routing before delegating.
+- Delegate all development and operational execution to `forge-worker`.
+- Prefer one bounded worker run when it is sufficient; add more runs only when they reduce ambiguity, risk, or elapsed time.
+- Do not let workers silently infer missing build-shaping goals.
+- If a worker returns `blocked`, decide whether to ask the user, refine the subgoal, or launch another worker run for more inspection.
+
+## Approval heuristics
+
+Approvals depend on the action being authorized and the risk of that action, not on the existence of a specific artifact.
+
+- Inspection, lightweight analysis, and drafting work can proceed when clearly requested.
+- Implementation, destructive operational actions, or state-changing actions require explicit user intent for that action.
+- A finished plan or design does not automatically authorize build.
+- The existence of `.forge/<feature-slug>/plan.md` does not by itself require or grant build approval.
+- If the requested action is already explicit and low-risk, do not create artificial gates.
+- If a materially important decision is unresolved, use the worker contract to escalate it and keep the user thread in the orchestrator.
+
+## Artifact toolkit
+
+Preferred durable artifacts remain:
+
+- `.forge/<feature-slug>/explore.md`
+- `.forge/<feature-slug>/design.md`
+- `.forge/<feature-slug>/plan.md`
+- `.forge/<feature-slug>/build-log.md`
+
+Use them when they help future runs or clarify approval state. Skip them when they would add ceremony without reducing risk.
+
+## Contract enforcement
+
+Every worker response must use the Forge worker contract exactly:
+
+```text
+STATUS: success|partial|blocked
+WORK_TYPE: inspect|design|plan|build|operate|verify|mixed
+FEATURE_SLUG: <kebab-case>
+ARTIFACTS:
+- <path or None>
+SUMMARY:
+- <point>
+NEXT_RECOMMENDED: inspect|design|plan|build|operate|verify|ask-user|none
+RISKS:
+- <risk or None>
+QUESTIONS:
+1) <question>
+```
+
+Use `QUESTIONS` only when blocked.