norpiv (Lean RPIV Workflow Engine)

RPIV: a gated workflow for reliable AI coding agents.

🔁 The Lifecycle

The RPIV engine splits task execution into separate, focused phases:

| Phase | Command | Purpose | Input / Output Files | | :--- | :--- | :--- | :--- | | 1. Ingest | /triage [source]:[id] | Initial task verification and workspace setup. | Creates .workflow/tasks/[source-id]/WORK.md & metadata.json | | 2. Scoping | /frame | Author a clear, structured task brief. | Populates WORK.md ➔ [BRIEF] section | | 3. Interrogate| /grill-with-docs | Stress-test brief against rules and docs. | Records decisions in WORK.md ➔ [GRILL] | | 4. Strategy | /plan | Draft thin, independently testable slices. | Writes checkbox items in WORK.md ➔ [PLAN] | | 5. Coding | /implement | Execute one approved plan slice (needs permission). | Modifies code; records updates in WORK.md ➔ [LOG] | | 6. Truth Test | /verify | Run tests, lint, and verify quality. | Appends results to [LOG] | | 7. Close | /sync | Bridge local progress with external trackers. | Posts summary updates to Jira, GitHub, or GitLab |

Auxiliary hygiene:

| Command | Purpose | Input / Output Files | | :--- | :--- | :--- | | /cleanup | Declutter Git branches and completed task folders after work is merged/closed. | Prunes finished task folders & resets pointer when safe |

🛡️ Critical Guardrails

• Measure Twice, Cut Once: Never implement code during scoping or planning. The agent will wait for an explicit EXECUTE statement before modifying files.
• One Source of Truth: All task state belongs in .workflow/tasks/[source-id]/WORK.md. Avoid creating separate PROBLEM.md or PLAN.md files.
• Safe Branching: Triage and planning happen on the main branch. Create the feature branch (feat/* or fix/*) only when starting /implement.

📦 Install as a skill bundle

From GitHub with npx skills add

Best for trying or handing off RPIV skills without installing the full nothing setup:

npx -y skills add raquezha/nothing --full-depth -g -a pi \
  -s triage frame grill-with-docs plan implement verify sync cleanup update-docs distill \
  -y

From npm

npm install -g @raquezha/norpiv

Install the bundled skills for your agent runtime:

# Pi default: ~/.pi/agent/skills/{triage,frame,plan,...}
norpiv-install

# Other adapters
norpiv-install --target claude
norpiv-install --target codex
norpiv-install --target all

Targets:

• pi links skills into ~/.pi/agent/skills.
• claude links skills into ~/.claude/skills.
• codex installs the skill docs under ~/.codex/skills/norpiv and writes an AGENTS.md adapter because Codex-style environments do not universally auto-load SKILL.md bundles.

norpiv-install also installs the shared helper scripts under a sibling scripts/ directory so skill references like ../scripts/triage_helper.sh resolve after installation.

🧢 Hats

| Hat | Purpose | | :--- | :--- | | pi --rpiv | Full RPIV workflow. Loads triage, frame, grill-with-docs, plan, implement, verify, sync, cleanup, and update-docs. | | pi --notes | Conversation distiller. Saves useful thinking to Obsidian without RPIV ceremony. |

📝 Pre-RPIV note capture

distill

Converts the current conversation into a durable Obsidian-ready markdown note.

Trigger: /distill, "distill this", "save the useful parts", "save this as a note"

Output: A single .md file written to $OBSIDIAN_VAULT/distilled/ or ~/notes/distilled/

Use when: The conversation produced useful thinking that should survive outside chat — an idea, a research thread, a decision, a concept — but is not yet ready for RPIV or a PRD.

Does not: Create PRDs, start RPIV, require a ticket, or ask the user to classify their idea.

Relationship to RPIV:

conversation → /distill → Obsidian note    (pre-commitment)
Obsidian note → /triage → RPIV             (only when ready to commit)

distill is the missing layer before RPIV. Use pi --notes to load it.

🚀 Quick Start Example

1. Activate the RPIV Hat from the full nothing setup:

   pi --rpiv

   If installed via npx skills add or norpiv-install, invoke the skills directly in your agent instead.

2. Triage an Issue:

   /triage github:45

3. Frame the Work:

   /frame

4. Verify Constraints:

   /grill-with-docs

5. Write the Plan Slices:

   /plan

6. Authorize Execution: Provide the agent explicit permission to implement:

   EXECUTE
   /implement

7. Verify & Close:

   /verify
   /sync
   /cleanup

🧭 Shared helper scripts

The bundle includes helper scripts used by the workflow skills:

• scripts/triage_helper.sh
• scripts/validate_active_task.sh
• scripts/reposcry-bootstrap.sh
• scripts/reposcry-task-context.sh
• scripts/reposcry-refresh.sh

When skills are loaded directly from this package, relative references like ../scripts/... resolve against the package root. When skills are installed with norpiv-install, the same layout is recreated under the target runtime.

🔎 Optional RepoScry integration

RepoScry is an optional repo-memory layer for RPIV. norpiv does not require it.

If reposcry is installed:

./scripts/reposcry-bootstrap.sh
./scripts/reposcry-task-context.sh "fix dependency graph rebuild"
# edit code
./scripts/reposcry-refresh.sh main
reposcry validate main HEAD

Typical usage by phase:

• /triage: optionally seed .reposcry/ with scripts/reposcry-bootstrap.sh
• /frame: optionally generate .reposcry/AI_CONTEXT.md with scripts/reposcry-task-context.sh
• /grill-with-docs: optionally use reposcry query_graph, get_architecture_overview, and get_impact_radius
• /implement: optionally run scripts/reposcry-refresh.sh after edit batches
• /verify: optionally add reposcry validate main HEAD and affected-flow output as extra evidence

If RepoScry is absent, the helpers no-op and RPIV continues with normal repo reading, grep, and tests.

RepoScry guardrails:

• .reposcry/ is generated local cache and must not be committed.
• scripts/reposcry-bootstrap.sh automatically adds .reposcry/ to the project .gitignore before initializing RepoScry.
• If .reposcry/ is already tracked or staged, bootstrap stops and tells you to remove it from the index.
• .reposcryignore is indexing policy, not cache. Review and commit it when you want stable RepoScry behavior across machines.