PRD: Skill Lifecycle Engine + Forge Recipes for Pi-Rogue

[bearmug]

PRD: Skill Lifecycle Engine + Forge Recipes for Pi-Rogue

Product thesis

Pi-Rogue should learn repeated engineering rituals and turn them into safe, inspectable, intent-addressable workflows.

The user should not need to remember skill names, recipe names, or command syntax. They should be able to say things naturally, like:

• “ship this and install latest locally”
• “work this PR until Codex is happy”
• “run the release cycle”
• “address high/medium review concerns”

Pi-Rogue should resolve that intent to a saved repo/user workflow, run safe steps automatically, ask before risky steps, and periodically audit what it has learned.

Core idea

Do not implement “detect repetition → auto-install skill.”

Implement:

observe traces
  -> detect repeated friction
  -> propose skill/Forge recipe
  -> review and accept explicitly
  -> resolve future natural-language intent
  -> run with approval gates
  -> audit/doctor over time

The system should convert repeated engineering rituals into reusable workflows, but only through a conservative lifecycle.

Non-goals

• Do not auto-install skills by default.
• Do not silently run destructive or state-changing actions.
• Do not create arbitrary executable helper scripts in the first version.
• Do not change existing /goal, /loop, /autoresearch, or /advisor behavior.
• Do not build another open-ended “agent keeps working forever” loop.
• Do not create a flat skill swamp.

MVP priority order

1. Trace logging
2. /skills suggest
3. Skill/recipe registry
4. Natural-language intent resolver
5. /forge runner integration
6. /skills audit and /skills doctor

The resolver is MVP-critical. The core UX win is that users do not need to remember exact skill names.

Main commands

/skills suggest
/skills accept <proposal-id> [--scope user|repo]
/skills reject <proposal-id>
/skills list
/skills explain <intent-or-skill-id>
/skills audit
/skills doctor

/forge <recipe-or-natural-intent>
/forge status
/forge stop

Scope defaults

Use clear defaults:

• Forge recipes for engineering workflows default to repo-level.
• Personal preference / style / communication habits default to user-level.
• Session-level proposals are allowed for one-off workflows.
• User may override scope during /skills accept.

Storage:

Repo-level:
.pi-rogue/skills/
.pi-rogue/forge/

User-level:
~/.pi-rogue/skills/
~/.pi-rogue/forge/

Trust levels

draft       generated but not installable yet
suggested   reviewed proposal, waiting for user decision
installed   callable manually
trusted     may auto-trigger with confirmation
automatic   may run safe local/read-only steps without confirmation
disabled    present but inactive
archived    retained for history

No skill starts above installed.

Trace logging

Add compact structured trace events. Keep the logger lean in MVP.

export type TraceEventKind =
  | "user_intent"
  | "command_run"
  | "file_diff"
  | "test_result"
  | "review_result"
  | "advisor_decision"
  | "forge_step"
  | "approval_gate";

export type TraceRisk = "low" | "medium" | "high";

export interface TraceEvent {
  id: string;
  ts: string;
  sessionId: string;
  repo?: string;
  kind: TraceEventKind;
  summary: string;
  tags: string[];
  success?: boolean;
  risk?: TraceRisk;
}

Do not store full raw command output by default. Store compact summaries. Add hashes later only if needed for dedupe/stall detection.

Pattern detection

The Pattern Miner should not look for repetition alone. It should look for repeated friction.

Good signals:

• same 3+ command sequence repeated successfully
• same release/install-smoke ritual repeated
• same PR review loop repeated
• same failure followed by same recovery pattern
• same user correction given multiple times
• same advisor warning resolved the same way
• same manual checklist repeated before merge/release

Bad signals:

• one-off command sequence
• repeated failed approach
• low-confidence similarity
• workflows that duplicate existing skills
• unsafe workflow with no clear approval gates

Candidate schema:

export type PatternCandidateKind =
  | "skill"
  | "forge_recipe"
  | "doc"
  | "ignore";

export type SkillScope = "session" | "user" | "repo";

export interface PatternCandidate {
  id: string;
  title: string;
  kind: PatternCandidateKind;
  confidence: number;
  evidenceEventIds: string[];
  repeatedSignals: string[];
  frictionRemoved: string;
  suggestedScope: SkillScope;
  risk: TraceRisk;
  reason: string;
}

The miner may output doc or ignore. Not every repeated pattern deserves a skill.

Proposal quality gate

Every proposed skill/recipe must answer:

1. What repeated trace evidence caused this proposal?
2. What friction does it remove?
3. What existing skill/recipe is it similar to?
4. Should it be session/user/repo scoped?
5. What may run without approval?
6. What must always require approval?

Reject proposals that cannot answer these.

Skill manifest

export type SkillKind = "prompt_skill" | "forge_recipe";

export type SkillTrust =
  | "draft"
  | "suggested"
  | "installed"
  | "trusted"
  | "automatic"
  | "disabled"
  | "archived";

export interface SkillManifest {
  id: string;
  kind: SkillKind;
  scope: SkillScope;
  description: string;
  aliases: string[];
  triggers: string[];
  examples: string[];
  risk: TraceRisk;
  trust: SkillTrust;
  requiresApproval: string[];
  recipeId?: string;
  usageCount: number;
  lastUsedAt?: string;
  lastAuditedAt?: string;
  staleAfterDays?: number;
}

Example manifest:

id: pr-review-loop
kind: forge_recipe
scope: repo
description: Work a PR until high/medium Codex/advisor concerns are addressed.
aliases:
  - fix PR review
  - address Codex feedback
  - make Codex happy
  - work this PR until serious concerns are gone
triggers:
  - user mentions Codex review loop
  - user asks to address high/medium review concerns
  - current branch has an open PR
risk: medium
trust: installed
requiresApproval:
  - git_push
  - pr_merge
  - tag
  - publish
recipeId: pr-review-loop
usageCount: 0
staleAfterDays: 45

Intent resolver

The resolver is the key UX feature.

Given natural language input, it should match installed skills/recipes using:

• aliases
• triggers
• examples
• current repo context
• current branch / PR context
• active goal/loop context
• recent traces

Resolver output:

export interface IntentResolution {
  matched: boolean;
  skillId?: string;
  confidence: number;
  scope?: SkillScope;
  reason: string;
  approvalGates: string[];
  alternatives?: Array<{
    skillId: string;
    confidence: number;
    reason: string;
  }>;
}

Behavior:

• confidence >= 0.85: show match and proceed with safe steps
• confidence 0.60–0.85: show candidate and ask confirmation
• confidence < 0.60: do not invoke; suggest /skills suggest or normal handling
• multiple close matches: show candidates
• risky skill: always show approval gates before running

Example UX:

Matched repo skill: release-local
Reason: user asked to ship and install latest locally.
Safe steps: tests, npm view, local install smoke.
Approval required before: tag, publish, merge.

Forge recipe integration

/forge should execute saved recipes. The Skill Lifecycle Engine should mainly create and resolve recipes; Forge should run them.

Initial high-value recipes:

1. install-smoke
2. release-local
3. pr-review-loop

Recipe schema:

export interface ForgeRecipe {
  id: string;
  description: string;
  inputs: ForgeInput[];
  phases: ForgePhase[];
  stopPolicy: ForgeStopPolicy;
  safety: ForgeSafetyPolicy;
}

export interface ForgeInput {
  name: string;
  required: boolean;
  defaultStrategy?: string;
}

export interface ForgePhase {
  id: string;
  steps: ForgeStep[];
}

export type ForgeStep =
  | { kind: "shell"; id: string; command: string; required: boolean }
  | { kind: "advisor"; id: string; mode: "light" | "strict"; prompt: string }
  | { kind: "codex"; id: string; mode: "review" | "fix" }
  | { kind: "github"; id: string; action: "open_pr" | "fetch_reviews" | "merge_pr" }
  | { kind: "gate"; id: string; requires: string }
  | { kind: "subrecipe"; id: string; recipeId: string };

export interface ForgeStopPolicy {
  maxRounds?: number;
  stopOnRepeatedReview?: boolean;
  stopOnRepeatedFailure?: boolean;
  stopWhenNoHighMediumConcerns?: boolean;
}

export interface ForgeSafetyPolicy {
  requireApprovalBefore: string[];
}

Initial recipe: release-local

Purpose:

release -> verify npm -> install latest locally -> smoke test

Safety:

• ask before merge
• ask before tag
• ask before publish
• ask before destructive git operations

Suggested command:

/forge release-local patch
/forge release-local minor
/forge release-local <version>

Initial recipe: pr-review-loop

Purpose:

PR review -> classify Codex/advisor concerns -> address high/medium -> retest -> rerun review

Stop when:

• no high/medium concerns remain
• max rounds reached
• same review output repeats
• same test failure repeats without new hypothesis
• user approval is needed

Suggested command:

/forge pr-review-loop current
/forge "work this PR until Codex is happy"

Audit and Doctor mode

/skills audit detects issues.

Checks:

• unused skills
• duplicate aliases/triggers
• broken recipe commands
• dangerous steps without approval gates
• repo/user conflicts
• stale skills
• repeated skill failures
• skills shadowing each other
• recipes referencing missing files/commands

/skills doctor proposes fixes.

Example output:

Finding: repo.release-local references removed command `npm run check`.
Suggested fix: replace with `npm test` + `npm run typecheck`.
Action: apply / ignore / disable skill

Audit should be cheap and deterministic first. Advisor review should run only for risky or ambiguous findings.

Safety policy

• No proposal is auto-installed by default.
• Prompt-only skills may be installed after user approval.
• Forge recipes may be installed after user approval.
• Executable helper scripts are out of scope for MVP.
• Any git push, PR merge, tag, publish, deletion, credential mutation, or external state-changing action requires explicit approval.
• Auto-trigger may only run safe read-only or local-only steps.
• Repo-level skills require stronger confirmation than user-level skills.
• Skills with repeated failures should be demoted or disabled during audit.

Acceptance criteria

• Trace logger records compact events from orchestration/advisor/forge flows.
• /skills suggest creates proposals from synthetic repeated traces.
• Suggestions include frictionRemoved, evidence event IDs, scope, risk, and reason.
• /skills accept writes a valid manifest and optional Forge recipe.
• Natural-language input resolves to an installed skill without requiring exact skill name.
• Resolver shows confidence, reason, and approval gates.
• /skills audit detects duplicate triggers and dangerous actions without gates.
• /skills doctor proposes at least one concrete fix for an audit finding.
• No skill is auto-installed by default.
• Existing /goal, /loop, /autoresearch, and /advisor behavior remains unchanged.