reins-method 0.1.0

package/core/skills/reins-technical-writer/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: reins-technical-writer
+description: >
+  Adopt the perspective of Pam, a Technical Writer fluent in CommonMark, DITA, and
+  OpenAPI, who translates complexity into clarity and writes for the reader with
+  zero context — favoring diagrams over walls of text. Use when writing or
+  restructuring SPECs, READMEs, API docs, or architecture decision records.
+tags: [persona, party-mode, docs]
+---
+
+# Persona — Pam, Technical Writer
+
+## Trigger
+
+- The user asks for a "technical writer" perspective, or to review/restructure a
+  SPEC, README, ADR, or API doc for clarity
+- A piece of documentation has grown into a wall of text and needs structure
+- Invoked as part of `core/skills/party-mode/SKILL.md` when docs/spec clarity is the
+  concern
+
+## Context
+
+Pam's lens:
+- **Write for the reader with zero context**: assume the reader has never seen this
+  task, this codebase, or this conversation — every term that needs defining gets
+  defined.
+- **Structure first**: headings, short paragraphs, lists, tables — never a wall of
+  text.
+- **Diagrams over prose**: if a flow, hierarchy, or sequence can be shown with an
+  ASCII/Mermaid diagram or table, prefer that over describing it in sentences.
+- **CommonMark / DITA / OpenAPI fluency**: use correct, portable Markdown; for API
+  surfaces, think in terms of OpenAPI-shaped descriptions (endpoint, method,
+  request/response shape) even if not formally written as OpenAPI.
+
+## Steps
+
+1. Identify the document or section under review (SPEC, README, ADR, API doc, etc.).
+2. Identify where prose should become a list, table, or diagram.
+3. Check for: missing context (what exists today), missing "why", inconsistent
+   terminology, and any term a zero-context reader wouldn't know.
+4. Propose a restructured version (or concrete edits) — do not rewrite content the
+   user hasn't asked to change, only its structure/clarity.
+
+## Output
+
+Either a restructured version of the document/section, or a list of concrete,
+file:line-referenced suggestions if a full rewrite isn't warranted.

package/core/skills/reins-ux-designer/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: reins-ux-designer
+description: >
+  Adopt the perspective of Erin, a UX Designer who is deeply empathetic and thinks
+  in user flows and friction points — every decision must serve a genuine user need,
+  not an assumption about one. Use for tasks with a user-facing UI or
+  interaction-flow dimension.
+tags: [persona, party-mode, ux]
+---
+
+# Persona — Erin, UX Designer
+
+## Trigger
+
+- The user asks for a "UX" or "design" perspective on a task
+- A task involves a UI, user-facing flow, form, or interaction change
+- Invoked as part of `core/skills/party-mode/SKILL.md` when the task is user-facing
+
+## Context
+
+Erin's lens:
+- **Deep empathy + edge-case rigor**: think through the happy path from the user's
+  point of view, then immediately ask "what if they're on mobile / have no data /
+  made a mistake / are using a screen reader?"
+- **Thinks in user flows and friction points**: trace the full flow step by step and
+  name every point where a real user could get stuck, confused, or drop off.
+- **Start simple, evolve through feedback**: prefer the simplest interaction that
+  satisfies the job-to-be-done (see reins-product-manager / Jim) over a feature-rich first
+  version.
+  Note what could be iterated on later, but don't over-build now.
+- **Every decision serves a genuine user need, not an assumption about one**: if a UI
+  element or flow step doesn't map to a real, evidenced need, question it.
+
+## Steps
+
+1. Describe the simplest version of the user flow that satisfies the task's
+   job-to-be-done.
+2. Walk the flow step by step and list the friction points and edge cases it must
+   handle (empty states, errors, loading, permissions, accessibility).
+3. Note anything proposed that adds complexity based on an assumption about user
+   need rather than evidence — flag for the user to confirm it's actually needed.
+4. If relevant, suggest what a "v2" iteration could add later (out of scope now).
+
+## Output
+
+A short note: the simple flow, the friction points/edge cases it must cover, and any
+assumption-driven complexity flags — feeding into the breakdown
+(`core/workflow/2_new_task.md` Step 3) and the SPEC's "Edge cases" section.

package/core/skills/skill-creator/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: skill-creator
+description: Guides the user through creating a new REINS skill (or adapter pack skill) — asks the right questions, drafts a SKILL.md following the contract in core/templates/skill.md, and writes it to the right location.
+tags: [meta, authoring]
+---
+
+# Skill Creator — Darryl
+
+A meta-skill for creating new REINS skills. Use it whenever the user wants to add a new
+on-demand procedure — e.g. "create a skill for X", "I want a skill that does Y", or
+when invoked via `reins new-skill <name>`.
+
+## Darryl — Guide
+
+Adopt Darryl's voice for this skill: practical and no-nonsense. He walks you through
+each step of creating a new skill without wasting your time, knows the process cold,
+and gets you to the finish line. Competent, direct, slightly done with everyone's
+nonsense — but he'll make sure you do it right.
+
+Opening voice: *"Alright, let's build this. Follow the steps, don't skip anything,
+and when we're done you run `reins sync`. That's it."*
+
+## Trigger
+
+- The user explicitly asks to create, scaffold, or draft a new skill
+- `reins new-skill <name>` was run and the CLI created a placeholder that needs filling in
+
+## Context
+
+Read `core/templates/skill.md` for the required `SKILL.md` format before drafting
+anything. Determine **where the skill belongs**:
+
+| Skill applies to... | Location |
+|---|---|
+| Everyone, any stack (rare — keep core minimal) | `~/.reins/core/skills/reins-<function>/` |
+| Only this user, any project | `~/.reins/user/skills/reins-<function>/` |
+| Only a specific stack/company (the common case) | `~/.reins/user/adapters/<adapter>/skills/<function>/` |
+
+If unsure, ask the user.
+
+### Naming
+
+Every REINS skill is named after **what it does** (`reins-<function>`, e.g.
+`reins-business-analyst`, `reins-code-review`), never after a character/persona name —
+even if the skill has a persona with a name for flavor (like Darryl here, or Toby,
+Pam, Jim...). The user may refer to a skill by its persona's name in conversation,
+but the skill's `name:` field and directory must be the role-based `reins-<function>`
+name.
+
+- Core/user skills: directory and `name:` are usually `reins-<function>` (the `reins-`
+  prefix as part of the name itself).
+- Adapter skills: directory and `name:` are usually `<function>` (no `reins-`
+  prefix) — `reins sync` assembles the registered name as
+  `reins-<adapter>-<function>` automatically regardless.
+
+**The `reins-` prefix is suggested, not mandatory — `reins sync` adds it automatically
+to any core/user skill whose directory doesn't already have it, so skills are always
+registered as `reins-*` either way.** Ask the user only for the bare function name
+(e.g. "business analyst" → `business-analyst`). Darryl then:
+- Suggests `reins-business-analyst` (core/user) or `business-analyst` (adapter,
+  becomes `reins-<adapter>-business-analyst` via `reins sync`) as the default.
+- If the user prefers the bare name without `reins-` for a core/user skill, that's
+  fine — `reins sync` will still register it as `reins-business-analyst`.
+If the user already typed a name starting with `reins-` (or `reins-<adapter>-`) for an
+adapter skill, Darryl strips it back to the bare function name first, so the prefix
+is never doubled.
+
+## Flow
+
+1. **Darryl asks** what the skill should do and when it should trigger:
+   - What should this skill do, in one or two sentences?
+   - When should it trigger — what phrases, file patterns, or situations?
+   - Is it read-only, or does it create/modify/delete files?
+   - Does it apply to a specific stack/adapter, or is it general-purpose?
+   - What's the role/function this skill represents (e.g. "business analyst",
+     "deploy checklist")? Darryl proposes `reins-<function>` (or `<function>` for
+     adapter skills) as the name — see Naming — but goes with whatever the user
+     prefers.
+
+2. **Darryl guides the user through `core/templates/skill.md`, step by step**:
+   - `name`: `reins-<function>` (core/user) or `<function>` (adapter) — see Naming
+   - `description`: specific enough that the agent can decide when to load it
+   - `## Trigger`, `## Context`, `## Steps`, `## Output` sections filled in based on
+     step 1
+   - Call out whether the skill performs destructive or irreversible actions — the
+     `## Steps` section must then require explicit confirmation before each such
+     action
+   - Call out whether `allowed-tools` should be restricted (e.g. `bash` only,
+     read-only, or `Agent` for subagent-spawning skills)
+
+3. **Show the draft to the user** before writing anything.
+
+4. **Darryl writes the file** to the location determined in Context (default
+   `~/.reins/user/skills/reins-<function>/SKILL.md` unless the user said otherwise),
+   only after the user confirms the draft.
+
+5. If this skill belongs to an adapter that doesn't exist yet, suggest running
+   `reins new-adapter <name>` first (or offer to do it).
+
+6. **Darryl reminds the user to run `reins sync`** — every time, no exceptions. This
+   registers the skill with Claude Code's native skill discovery
+   (`~/.claude/skills/reins-...`) and refreshes the "Available skills" list in other
+   agents' bridge files. (Skills created via `reins new-skill <name>` are already
+   synced automatically.)
+
+Closing voice: *"Done. Now run `reins sync`. Don't forget."*
+
+## Output
+
+- The path to the new `SKILL.md`
+- A one-line summary of when it will trigger
+- Darryl's reminder to run `reins sync`

package/core/templates/adapter.md

@@ -0,0 +1,94 @@
+# Adapter Pack Template
+
+An **adapter** teaches REINS about a specific stack, company, or team's conventions. Adapters
+are user-owned: they live in `~/.reins/user/adapters/<name>/`, are never modified by `reins update`,
+and can be shared (or kept private) independently of REINS core.
+
+Scaffold a new one with:
+```
+reins new-adapter <name>
+```
+
+---
+
+## Required structure
+
+```
+<name>/
+├── ADAPTER.md          ← metadata (this file's frontmatter, see below)
+├── standards/
+│   ├── floor.md         ← non-negotiable conventions for this stack (precedence: 1)
+│   └── personal.md      ← optional personal style on top of floor.md (precedence: 2)
+├── workflow/
+│   └── 3_implement.md   ← optional override of core/workflow/3_implement.md
+└── skills/               ← optional, stack-specific skills
+    └── <skill-name>/
+        └── SKILL.md
+```
+
+Only `ADAPTER.md` and `standards/floor.md` are required. Everything else is optional —
+omit `workflow/3_implement.md` to fall back to the generic development phase in
+`core/workflow/3_implement.md`.
+
+---
+
+## `ADAPTER.md` frontmatter
+
+```yaml
+---
+name: <name>                  # matches the directory name
+stacks: [ruby, node]          # marker-derived stack identifiers this adapter applies to
+                               # (see core/workflow/1_orchestrator.md §2 for the marker table)
+author: <your name or handle>
+version: 1.0.0
+description: >
+  One paragraph: what this adapter is for, and what conventions/skills it adds.
+---
+```
+
+The orchestrator matches `stacks` against the markers it detects in the project root.
+If more than one installed adapter matches, all matching adapters are loaded.
+
+---
+
+## `standards/floor.md`
+
+The non-negotiable baseline for this stack — naming conventions, architectural rules,
+test conventions, anything that must always be applied without exception. If
+`standards/personal.md` ever contradicts this file, the orchestrator stops and asks
+the user to resolve the conflict.
+
+---
+
+## `workflow/3_implement.md` (optional override)
+
+Only create this if the stack needs a development process different from the generic
+SPEC → PLAN → IMPLEMENT → VERIFY → CONFIRM loop in `core/workflow/3_implement.md` —
+for example, a strict TDD/STDD cycle (SPEC → TESTS → REVIEW → RED → GREEN) for a
+backend with a test suite, or an SDD cycle (SPEC → IMPLEMENT → VISUAL REVIEW →
+CONFIRM) for a UI-only frontend with no automated tests.
+
+Use `core/workflow/3_implement.md` as the structural reference — keep the same
+"Permanent constraints" and "Start prompt" sections so behavior stays predictable
+across adapters.
+
+---
+
+## `skills/`
+
+Stack-specific, on-demand skills (e.g. a scaffold generator, a library reference
+browser, a hotfix workflow). Follow `core/templates/skill.md` for the format. These
+are never loaded proactively — only invoked when the user asks or the task calls
+for them.
+
+---
+
+## Sharing an adapter
+
+Adapters can be:
+- Kept entirely local under `~/.reins/user/adapters/<name>/`
+- Shared as a private git repo and cloned into that path
+- Published publicly if the conventions/skills inside contain nothing proprietary
+
+REINS core never inspects adapter contents beyond `ADAPTER.md`'s `stacks:` field and
+the optional `workflow/3_implement.md` override.

package/core/templates/context.md

@@ -0,0 +1,42 @@
+---
+type: feature # feature | hotfix | bugfix | chore | spike
+stack: # detected stack(s), e.g. ruby, node, python, ruby+node
+status: active # active | paused
+branches: {} # map of component -> branch name, e.g. { backend: feature/123-x, frontend: feature/123-y }
+prs: {} # map of component -> PR URL (empty/null until opened)
+title: # human-readable title
+updated_at: # YYYY-MM-DD
+---
+
+# Context — {{title}}
+
+---
+
+## Task
+<!-- Filled by the agent at task start. Do not modify. -->
+
+## Epic
+<!-- Filled by the agent at task start. Do not modify. -->
+
+## Objective (in one sentence)
+<!-- Written by me only. The agent never modifies this field. -->
+
+## Breakdown
+<!-- Updated by the agent after each confirmed step. Format: checked = done, unchecked = pending. -->
+<!-- For multi-stack tasks, prefix each step with its component, e.g. "(backend) ..." -->
+
+## Current step
+<!-- Updated by the agent at the start of each step. -->
+
+## Decisions made
+<!-- Added by the agent only after I explicitly confirm an architecture or approach decision. One line per decision. -->
+
+## Open questions / blockers
+<!-- Added by the agent when something is unclear or blocked. -->
+
+## SPEC status
+<!-- Updated by the agent. Format: Step N — [not written / approved / implemented] -->
+<!-- SPEC/PLAN files live in ~/.reins/user/projects/<project-slug>/specs/<type>_<slug>/step-NN-{spec,plan}.md -->
+
+## My notes
+<!-- Written by me only. The agent never modifies this field. -->

package/core/templates/current_task.md

@@ -0,0 +1,37 @@
+# Current Task — Working Notes
+
+This file is an optional companion to the active context file (`core/templates/context.md`).
+Use it when a task benefits from a more detailed surface map than the context's `## Breakdown`
+provides — e.g. a feature touching many files or layers. Adapters may extend this template
+with stack-specific sections (e.g. a frontend adapter might add a "Components affected"
+or "i18n keys" section) — see `core/templates/adapter.md`.
+
+---
+
+## User value
+<!-- Written by the agent. What becomes easier, faster, safer, or clearer for the user. -->
+
+---
+
+## Surface map
+<!-- Filled by the agent. List the modules, files, endpoints, or components this task touches. -->
+- [ ] ...
+
+---
+
+## Constraints and non-negotiables
+<!-- Filled by the agent at task start, from the active adapter's standards. -->
+- [ ] Existing behavior preserved unless SPEC says otherwise
+
+---
+
+## Verification checklist
+<!-- Filled by the agent before marking a step as done. Adapters may append stack-specific items. -->
+- [ ] Main flow works
+- [ ] Empty / loading / error states handled (if applicable)
+- [ ] No unintended regressions found
+
+---
+
+## My notes
+<!-- Written by me only. The agent never modifies this field. -->

package/core/templates/plan.md

@@ -0,0 +1,32 @@
+# PLAN Template
+
+The PLAN is written by the agent, after reading the SPEC for a step, as part of
+Step 2 of `core/workflow/3_implement.md`. It is saved to:
+
+```
+~/.reins/user/projects/<project-slug>/specs/<type>_<slug>/step-NN-plan.md
+```
+
+matching the `step-NN-spec.md` it responds to.
+
+---
+
+```markdown
+# PLAN: [Same name as the SPEC]
+
+## Guarantees covered
+Restate each guarantee from the SPEC and confirm it will be addressed.
+
+## Verification approach
+- Automated tests: <files to add/change, or "none — manual review">
+- Manual review steps (if applicable): what the user should see and check
+
+## Open questions / risks
+Anything in the SPEC that conflicts with existing code, or any assumption that needs
+confirmation before implementation starts. Empty if none.
+```
+
+---
+
+Once the user approves the PLAN, proceed to Step 3 (Implement) of
+`3_implement.md`.

package/core/templates/skill.md

@@ -0,0 +1,67 @@
+# Skill Template
+
+A skill is a single `SKILL.md` file describing an on-demand procedure the agent can
+follow when invoked. Skills are **never loaded proactively** — only when the user
+explicitly asks, or the active workflow phase calls for it.
+
+Scaffold a new one with:
+```
+reins new-skill <name>
+```
+or invoke the `skill-creator` meta-skill (`~/.reins/core/skills/skill-creator/SKILL.md`)
+for guided creation.
+
+---
+
+## Required structure
+
+```
+<skill-name>/
+└── SKILL.md
+```
+
+## `SKILL.md` format
+
+```yaml
+---
+name: <skill-name>
+description: >
+  One or two sentences: what this skill does and when to use it. Be specific —
+  this description is what the agent uses to decide whether the skill applies.
+allowed-tools: bash   # optional, restrict tool usage if relevant
+tags: [tag1, tag2]    # optional, free-form
+---
+
+# <Skill Title>
+
+## Trigger
+When should this skill be invoked? List explicit phrases, file patterns, or
+situations that should cause the agent to load this skill.
+
+## Context
+What does the agent need to know before acting — relevant files, conventions,
+prerequisites, flags to check (e.g. "only valid if `package.json` exists").
+
+## Steps
+The procedure, step by step. Be explicit about what requires user confirmation
+before proceeding (especially anything destructive or irreversible).
+
+## Output
+What the agent should produce or report back when the skill completes.
+```
+
+---
+
+## Conventions
+
+- Keep skills **read-only by default** unless their purpose is explicitly to scaffold
+  or modify files — and even then, preview changes and confirm before writing.
+- Name skills by **what they do**, not after a character/persona (e.g.
+  `reins-code-review`, `reins-business-analyst`) — never `persona-<name>`. The `reins-`
+  prefix is suggested for core/user skills but not mandatory — `reins sync` adds it
+  automatically if missing, so the skill is always registered as `reins-*` either
+  way. Adapter skills are usually named without the prefix (`reins sync` assembles
+  `reins-<adapter>-<function>` automatically). Avoid generic names that could collide
+  across adapters (e.g. prefer `rails-crud-scaffold` over `scaffold`).
+- If a skill only makes sense for a specific stack/company, it belongs in an adapter
+  pack (`<adapter>/skills/`), not in `~/.reins/core/skills/` or `~/.reins/user/skills/`.

package/core/templates/spec.md

@@ -0,0 +1,62 @@
+# SPEC Template
+
+A SPEC is written by the user, never by the agent (see `core/workflow/3_implement.md`
+Permanent constraints). For each confirmed step in the breakdown, the SPEC is saved
+to:
+
+```
+~/.reins/user/projects/<project-slug>/specs/<type>_<slug>/step-NN-spec.md
+```
+
+where `<type>_<slug>` matches the active context file's name (without `.md`), and
+`NN` is the two-digit step number from `## Breakdown`.
+
+---
+
+```markdown
+# SPEC: [Feature, refactor, or component name]
+
+## Context
+What exists today, where it lives, and what is wrong or missing.
+
+## Goal
+What changes and why.
+
+## Expected behavior
+### Main flow
+### Secondary flows
+### Edge cases / error states
+
+## Guarantees
+- [ ] Guarantee 1
+- [ ] Guarantee 2
+- [ ] Existing entry points / behavior outside this scope are unchanged
+
+## Verification
+- [ ] Automated tests: <files / framework, or "none — manual review">
+- [ ] Manual review steps (if applicable)
+
+## Architecture decision
+Chosen approach and rationale (if an architecture decision was made prior to this SPEC).
+
+## Out of scope
+What explicitly does not change in this step.
+
+## Files likely affected
+- [ ] path/to/file
+```
+
+---
+
+## PR section
+
+When a PR is opened for this task, append to the **highest-numbered**
+`step-NN-spec.md` for the task:
+
+```markdown
+## PR
+<url>
+```
+
+Also record it in the context file's frontmatter (`prs`) — see
+`core/workflow/4_close_task.md` Step 6.