reins-method 0.1.0

package/SKILLS.md

@@ -0,0 +1,111 @@
+# Skills
+
+A skill is a single `SKILL.md` file describing an on-demand procedure. Skills are
+**never loaded proactively** — the agent reads them only when you explicitly ask, or
+when a workflow phase clearly calls for it.
+
+---
+
+## Where skills live
+
+| Skill applies to... | Location |
+|---|---|
+| Everyone, any stack (rare — keep core minimal) | `~/.reins/core/skills/<name>/` |
+| Only you, any project | `~/.reins/user/skills/<name>/` |
+| Only a specific stack/company | `~/.reins/user/adapters/<adapter>/skills/<name>/` |
+
+Most custom skills belong in an adapter (if stack/company-specific) or in
+`~/.reins/user/skills/` (if personal and general-purpose).
+
+---
+
+## Creating a skill
+
+```bash
+reins new-skill my-skill
+```
+
+This scaffolds `~/.reins/user/skills/my-skill/SKILL.md`. Or, for guided creation, ask
+your agent to use the **skill-creator** meta-skill
+(`~/.reins/core/skills/skill-creator/SKILL.md`) — it will ask what the skill should do,
+when it should trigger, whether it's read-only, and where it belongs (user vs.
+adapter), then draft the file for your review before writing it.
+
+---
+
+## `SKILL.md` format
+
+```yaml
+---
+name: my-skill
+description: >
+  One or two sentences: what this skill does and when to use it. Be specific —
+  this is what the agent uses to decide whether the skill applies.
+allowed-tools: bash   # optional
+tags: [tag1, tag2]    # optional
+---
+
+# My Skill
+
+## Trigger
+Explicit phrases, file patterns, or situations that should cause this skill to load.
+
+## Context
+What the agent needs to know before acting: relevant files, conventions,
+prerequisites, flags to check.
+
+## Steps
+The procedure, step by step. Be explicit about what requires confirmation before
+proceeding — especially anything destructive or irreversible.
+
+## Output
+What the agent should produce or report when done.
+```
+
+---
+
+## Conventions
+
+- **Read-only by default.** If a skill scaffolds or modifies files, it must preview
+  the changes and ask for confirmation before writing.
+- **Specific names.** Avoid generic names that could collide across adapters (prefer
+  `rails-crud-scaffold` over `scaffold`).
+- **Specific descriptions.** The `description` field is how the agent decides whether
+  to load the skill — vague descriptions cause skills to be missed or over-triggered.
+- **Stack-specific skills belong in adapters**, not in `core/` or `user/skills/`.
+
+---
+
+## Example
+
+```yaml
+---
+name: rails-crud-scaffold
+description: >
+  Generate a CRUD scaffold (model, migration, controller, serializer, request specs)
+  for a new Rails resource, following this project's conventions. Use when asked to
+  "scaffold", "generate CRUD", or "add a new resource" in a Ruby/Rails project.
+allowed-tools: bash
+tags: [scaffold, ruby]
+---
+
+# Rails CRUD Scaffold
+
+## Trigger
+User asks to scaffold/generate a new resource in a Rails project (`Gemfile` present).
+
+## Context
+Read `standards/floor.md` for naming and folder conventions before generating
+anything. Determine the resource name and attributes from the request; ask if
+ambiguous.
+
+## Steps
+1. Propose the list of files to be created/modified and their contents (preview only).
+2. Wait for confirmation.
+3. Write the files.
+4. Run the relevant generator/test command (if any) and report the result.
+
+## Output
+- List of files created/modified
+- Any follow-up steps (e.g. run migrations)
+```

package/agents/README.md

@@ -0,0 +1,61 @@
+# Agent Bridge Files
+
+The files in this directory (`CLAUDE.md`, `GEMINI.md`, `AGENTS.md`,
+`copilot-instructions.md`) are **generated** by `reins install` / `reins update` from
+`~/.reins/user/config.yaml` — do not edit them by hand, your changes will be
+overwritten on the next `reins update`.
+
+They all carry the same content: an import of `core/workflow/1_orchestrator.md`,
+the user's standards, the active adapters, and the historic mode flag.
+
+`reins install`/`reins update`/`reins sync` then wire **every agent detected on this
+machine** (its config directory already exists) to read the corresponding bridge
+file, inside a clearly marked block — not just the one agent picked during `reins
+install`. The generic `~/AGENTS.md` fallback is always wired. If you install a
+new AI agent later, run `reins link-agents` to wire it in without a full `reins
+update`.
+
+```
+<!-- REINS:BEGIN -->
+... managed content ...
+<!-- REINS:END -->
+```
+
+Only the content between these markers is touched — everything else in your native
+config file (e.g. `~/.claude/CLAUDE.md`) is left alone.
+
+| Agent | Bridge file | Native target | Mechanism |
+|---|---|---|---|
+| Claude Code | `CLAUDE.md` | `~/.claude/CLAUDE.md` | `@~/.reins/agents/CLAUDE.md` import |
+| Gemini CLI | `GEMINI.md` | `~/.gemini/GEMINI.md` | `@~/.reins/agents/GEMINI.md` import |
+| GitHub Copilot CLI | `copilot-instructions.md` | `~/.copilot/instructions.md` | reference note (no native import syntax) |
+| Codex CLI | `AGENTS.md` | `~/.codex/AGENTS.md` | reference note |
+| Aider / OpenCode / Cursor / other | `AGENTS.md` | `~/AGENTS.md` | reference note |
+
+For agents without a native "import another file" mechanism, the managed block is a
+short pointer to the bridge file. Until that agent supports imports, open the bridge
+file directly (e.g. `cat ~/.reins/agents/AGENTS.md`) or paste its content where needed —
+`reins doctor` will flag this so you know it needs attention.
+
+---
+
+## Skill registration
+
+Every bridge file ends with an **"Available skills"** section: a generated list of
+every skill under `core/skills/`, `user/skills/`, and active adapters' `skills/`,
+with their `name`, `description`, and path — built by `collect_skills` /
+`skill_frontmatter` in `bin/reins`. This is how agents without a native skill-discovery
+directory (Gemini CLI, Copilot CLI, Codex CLI, Aider/OpenCode/other) find out what
+skills exist and when to use them.
+
+**Claude Code** additionally has a native Agent Skills directory at
+`~/.claude/skills/`. `reins install` / `reins update` / `reins new-skill` / `reins sync` all
+call `sync_skills`, which (when `~/.claude/` exists, regardless of which agent is
+configured as primary) maintains a symlink per REINS skill at
+`~/.claude/skills/reins-<name>` (or
+`~/.claude/skills/reins-<adapter>-<name>` for adapter skills) pointing at the skill's
+directory in `~/.reins/`. These symlinks are namespaced with the `reins-` prefix so they
+can be safely added/removed without touching any of your own Claude Code skills.
+
+`reins uninstall` removes all `reins-*` symlinks from `~/.claude/skills/` (in addition to
+removing the managed block from your agent's native config).