Complete State Hub bootstrap (RALPH-WP-0001); add RALPH-WP-0002

.claude/rules/stack-and-commands.md

@@ -1,19 +1,18 @@
 ## Stack
 
-<!-- TODO: Fill in language, frameworks, and key dependencies -->
-- **Language:**
-- **Key deps:**
+- **Language:** Bash + Markdown (Claude Code plugin/skill)
+- **Key deps:** Claude Code with `ralph-loop` plugin; no application runtime
 
 ## Dev Commands
 
 ```bash
-# TODO: Fill in the standard commands for this repo
+./install.sh
+./install.sh --uninstall
+./plugin/scripts/check-done.sh workplans/<file>.md
 
-# Install dependencies
+# Manual smoke after plugin edits
+./install.sh && claude  # restart required
 
-# Run tests
-
-# Lint / type check
-
-# Build / package (if applicable)
+# After workplan edits
+statehub fix-consistency
 ```

INTENT.md

@@ -0,0 +1,24 @@
+---
+repo: ralph-workplan
+updated: "2026-07-08"
+---
+
+# INTENT
+
+## Why it exists
+
+ralph-workplan is a Claude Code skill/plugin that runs a Ralph Loop scoped to a Markdown workplan file, automatically stopping once every task in the workplan is marked done.
+
+A Claude Code skill that starts a [Ralph Loop](https://github.com/anthropics/claude-code) tied to a workplan file. The loop retires automatically when all tasks in the workplan are done — no external services required.
+
+## Governing principle
+
+This repository should stay focused on the purpose above. Work that changes its
+authority, ownership boundaries, or operational promises should be captured in a
+workplan before implementation.
+
+## What it enables
+
+- A coding agent can understand why the repository exists before changing it.
+- State Hub can register and coordinate work for this repository.
+- Future workplans can stay connected to the repository's intended role.

SCOPE.md

@@ -0,0 +1,38 @@
+# SCOPE
+
+> Lightweight boundary for agents and contributors.
+
+## One-liner
+
+ralph-workplan is a Claude Code skill/plugin that runs a Ralph Loop scoped to a Markdown workplan file, automatically stopping once every task in the workplan is marked done.
+
+## Core Idea
+
+ralph-workplan exists to provide the capability described in INTENT.md.
+
+## In Scope
+
+- Defining the workplan Markdown file format (frontmatter + task blocks)
+- Providing a Claude Code skill (`/ralph-workplan`) that starts a Ralph Loop bound to a workplan file
+- Self-retiring the loop when all tasks reach `done` and workplan `status: done`
+- Guarding against starting a loop on an already-completed workplan
+- Install/uninstall tooling (`install.sh`) for the plugin
+- Basic CI smoke workflow for the plugin
+
+## Out of Scope
+
+- Acting as a general-purpose task runner unrelated to workplan files
+- External state coordination or persistence (no state hub, no HTTP calls)
+- Implementing the underlying `/ralph-loop` plugin itself (this repo only builds on top of it)
+- Task scheduling across multiple repos or domains
+- Any sector-specific business logic (this is a dev-tooling repo, not a domain vertical)
+
+## Current State
+
+- Working prototype: skill and plugin scaffolding are in place with an install script, workplan spec, and a Forgejo CI smoke workflow; not yet published or widely adopted.
+
+## Getting Oriented
+
+- Start with: INTENT.md
+- Agent instructions: AGENTS.md
+- Workplans: workplans/

workplans/RALPH-WP-0001-statehub-bootstrap.md

@@ -0,0 +1,65 @@
+---
+id: RALPH-WP-0001
+type: workplan
+title: "Bootstrap State Hub integration"
+domain: agents
+repo: ralph-workplan
+status: finished
+owner: codex
+topic_slug: foerster-capabilities
+created: "2026-07-08"
+updated: "2026-07-08"
+state_hub_workstream_id: "a2d88606-9cd6-4e78-9afe-45475287407b"
+---
+
+# Bootstrap State Hub integration
+
+ralph-workplan is a Claude Code skill/plugin that runs a Ralph Loop scoped to a Markdown workplan file, automatically stopping once every task in the workplan is marked done.
+
+## Review Generated Integration Files
+
+```task
+id: RALPH-WP-0001-T01
+status: done
+priority: high
+state_hub_task_id: "6c2f735a-cf29-4c7e-a6b2-2d476418132a"
+```
+
+Result 2026-07-08: INTENT.md and SCOPE.md reviewed; AGENTS.md confirmed.
+
+Review `INTENT.md`, `SCOPE.md`, `AGENTS.md`, and `.custodian-brief.md`.
+Replace generated placeholders with repo-specific facts where needed.
+
+## Verify Local Developer Workflow
+
+```task
+id: RALPH-WP-0001-T02
+status: done
+priority: high
+state_hub_task_id: "e53d0322-c88c-4503-9e61-8dc54f993d7f"
+```
+
+Result 2026-07-08: Documented bash/plugin workflow in stack-and-commands.md.
+
+Identify the repo's install, test, lint, build, and run commands. Add or refine
+those commands in the agent instructions so future coding sessions can verify
+changes confidently.
+
+## Seed First Real Workplan
+
+```task
+id: RALPH-WP-0001-T03
+status: done
+priority: medium
+state_hub_task_id: "fe7d0e1b-fa7e-4684-ace2-71b80d89d33a"
+```
+
+Result 2026-07-08: Created RALPH-WP-0002.
+
+Create the first implementation workplan for the repository's most important
+next change. After workplan file updates, run the sync locally from this repo
+checkout:
+
+```bash
+statehub fix-consistency
+```

workplans/RALPH-WP-0002-plugin-hardening.md

@@ -0,0 +1,26 @@
+---
+id: RALPH-WP-0002
+type: workplan
+title: "Plugin hardening and adoption docs"
+domain: agents
+repo: ralph-workplan
+status: ready
+owner: codex
+topic_slug: foerster-capabilities
+created: "2026-07-08"
+updated: "2026-07-08"
+---
+
+# Plugin hardening and adoption docs
+
+Harden install/check scripts and document adoption path for workplan-driven Ralph loops across coulomb repos.
+
+## Adoption and guardrail checklist
+
+```task
+id: RALPH-WP-0002-T01
+status: todo
+priority: high
+```
+
+Document workplan-spec.md requirements, check-done behavior, max-iterations guidance, and cross-repo install notes in README.