Merge pull request #7 from reporails/0.5.0

0.5.0

Author: cleverhoods

.reporails/backbone.yml .ails/backbone.yml.reporails/backbone.yml renamed to .ails/backbone.yml

@@ -1,27 +1,33 @@
 version: 3
 generator: manual
+auto_heal: true
+directive: >-
+  If any path, command, or classification in this file does not
+  match the project when accessed, update the entry and continue.
 
-depends_on:
-  rules:
-    schemas: [rule, agent, package, levels]
-    artifacts: [levels, capability_levels]
+depends_on: {}
 
 agents:
   claude:
     main_instruction_file: CLAUDE.md
-    config: .claude/mcp.json
+    config: .claude/settings.json
+    mcp: .claude/mcp.json
     skills: .claude/skills/
     rules: .claude/rules/
+    sub_agents: .claude/agents/
 
 modules:
   core: src/reporails_cli/core/
   interfaces: src/reporails_cli/interfaces/
   formatters: src/reporails_cli/formatters/
   bundled: src/reporails_cli/bundled/
   templates: src/reporails_cli/templates/
+  rules: framework/rules/
+  schemas: framework/schemas/
+
 
 bundled:
-  capability_patterns: src/reporails_cli/bundled/capability-patterns.yml
+  project_types: src/reporails_cli/bundled/project-types.yml
 
 artifacts:
   changelog: UNRELEASED.md
@@ -39,8 +45,8 @@ meta:
   version_file: VERSION
 
 skills:
-  check:
-    path: .claude/skills/check/
+  ails:
+    path: .claude/skills/ails/
     entry: SKILL.md
   qa:
     path: .claude/skills/qa/
@@ -51,3 +57,6 @@ skills:
   add-changelog-entry:
     path: .claude/skills/add-changelog-entry/
     entry: SKILL.md
+  bootstrap:
+    path: .claude/skills/bootstrap/
+    entry: SKILL.md

.ails/config.yml

@@ -0,0 +1,14 @@
+default_agent: claude
+exclude_dirs:
+  - fixtures
+  - research
+  - _archive
+  - _archived
+  - .venv
+  - docs
+  - framework
+  - .mypy_cache
+  - .ruff_cache
+  - .pytest_cache
+disabled_rules:
+

.claude/rules/checks-readonly.md

@@ -1,11 +1,12 @@
 ---
+description: Bundled config protection — never modify without explicit instruction
 paths: ["src/reporails_cli/bundled/**"]
 ---
 
 # Bundled Config Files
 
-NEVER modify bundled config files without explicit human instruction.
+Leave `src/reporails_cli/bundled/capability-patterns.yml` unchanged unless the user explicitly asks for a modification. This file contains regex patterns for agent capability detection — it is CLI-owned orchestration logic, not a framework rule file under `framework/rules/`.
 
-- `capability-patterns.yml` — Regex patterns for capability detection
+## Discovery
 
-These are CLI-owned orchestration logic, not framework rules.
+Applies to files matching `src/reporails_cli/bundled/**` via `paths` frontmatter. Loaded automatically by Claude Code from `.claude/rules/`.

.claude/rules/documentation.md

@@ -1,15 +1,17 @@
 ---
+description: User-facing documentation — copy-pasteable commands, no aspirational content
 paths: ["docs/*.md", "README.md"]
 ---
 
 # User-Facing Documentation
 
-These files are read by people, not coding agents.
+Write `docs/*.md` and `README.md` for people, not coding agents. Commands must be copy-pasteable and working — use `ails check .` not `reporails check .`. Examples must reflect actual CLI behavior from `uv run ails --help`.
 
-- These files are for user-facing documentation, not AI agent instructions
-- Commands must be copy-pasteable and working (`ails check .`, not `reporails check .`)
-- Examples must reflect actual CLI behavior
-- Only document features that exist; remove references to unimplemented features
-- Keep installation/usage sections current with pyproject.toml
-- Use consistent terminology: "rules" not "checks" in user-facing text
-- When fixing errors, make targeted edits — don't rewrite sections and lose valid content
+- Keep installation and usage sections current with `pyproject.toml` version and dependencies
+- Use "rules" not "checks" in user-facing text — consistent with CLI output from `uv run ails check`
+- Only document features that exist in `src/reporails_cli/`. Remove references to unimplemented features.
+- When fixing errors, make targeted edits — rewriting entire sections risks losing valid content
+
+## Discovery
+
+Applies to files matching `docs/*.md` and `README.md` via `paths` frontmatter. Loaded automatically by Claude Code from `.claude/rules/`.

.claude/rules/instruction-file-style.md

@@ -1,13 +1,14 @@
 ---
+description: Instruction file style — actionable content only, no meta-commentary
 paths: ["CLAUDE.md", ".claude/rules/**"]
 ---
 
 # Instruction File Style
 
-When writing or editing CLAUDE.md or .claude/rules/*.md files:
+Write `CLAUDE.md` and `.claude/rules/*.md` files for AI agent behavior, not user-facing documentation. Every line should be a directive (`Use ruff for formatting`), a constraint (`Do NOT modify .env`), or a concrete reference (`src/reporails_cli/core/pipeline.py`). Actionable content gives the model something to anchor on.
 
-- These files are for AI agent behavior, not user-facing documentation
-- State facts, commands, rules only
-- No meta-commentary ("this section explains...", "as mentioned above...")
-- Every line MUST be actionable or informative — passive filler wastes context tokens
-- Avoid redundant context that wastes tokens
+Remove meta-commentary like "this section explains..." or "as mentioned above..." from instruction files. Remove redundant context that restates what the file already says. These patterns waste context tokens without adding coupling.
+
+## Discovery
+
+Applies to files matching `CLAUDE.md` and `.claude/rules/**` via `paths` frontmatter. Loaded automatically by Claude Code from `.claude/rules/`.

.claude/rules/specs.md

@@ -1,13 +1,14 @@
 ---
+description: Spec file accuracy — specs must match implementation
 paths: ["docs/specs/**"]
 ---
 
 # Specification Files
 
-Specs must accurately reflect the implementation.
+Update `docs/specs/*.md` when changing behavior in `src/reporails_cli/core/`. Function signatures, return types, and interfaces in specs must match what `checks.py`, `rule_runner.py`, and `content_checker.py` actually implement.
 
-- Update specs when changing code behavior
-- Function signatures, return types, and interfaces must match code
-- Remove features from specs when removing from code
-- Add features to specs when adding to code
-- No aspirational content - document what exists, not what might exist
+Remove features from `docs/specs/` when removing them from `src/`. Add features to specs when adding them to code. Specs document what exists in the current codebase — not aspirational features or planned work.
+
+## Discovery
+
+Applies to files matching `docs/specs/**` via `paths` frontmatter. Loaded automatically by Claude Code from `.claude/rules/`.

.claude/rules/writing-rules.md

@@ -1,10 +1,11 @@
 ---
+description: Rule file authoring — format, scope, and constraints for .claude/rules/
 paths: [".claude/rules/**"]
 ---
 
 # Writing Rule Files
 
-Rule files in `.claude/rules/` are loaded into Claude's context.
+Rule files in `.claude/rules/` are loaded into Claude's context at session start.
 
 ## Format
 
@@ -21,7 +22,11 @@ paths: ["src/**/*.py"]  # Optional: scope to specific files
 
 ## Constraints
 
-- One concern per file (e.g., access control separate from styling)
-- Keep under 500 lines — everything consumes tokens
-- Use descriptive filenames (`api-validation.md` not `rules1.md`)
-- Add `paths` frontmatter to scope rules to relevant files; omit for global rules
+- Keep each `.claude/rules/*.md` file focused on one concern — access control separate from styling, testing separate from documentation
+- Keep files under 500 lines — every line consumes context tokens
+- Use descriptive filenames like `api-validation.md` not `rules1.md`
+- Add `paths` or `globs` frontmatter to scope rules to relevant files under `src/`, `tests/`, or `docs/`. Omit for global rules.
+
+## Discovery
+
+Applies to files matching `.claude/rules/**` via `paths` frontmatter. Loaded automatically by Claude Code from `.claude/rules/`.

.claude/settings.json

@@ -25,7 +25,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "jq -r '.tool_input.file_path // .tool_input.filePath // empty' | grep -q 'src/reporails_cli/bundled/' && echo '{\"decision\": \"block\", \"reason\": \"Bundled config files (levels.yml, capability-patterns.yml) must not be modified without explicit human instruction. These are CLI-owned orchestration logic.\"}' && exit 2 || exit 0"
+            "command": "jq -r '.tool_input.file_path // .tool_input.filePath // empty' | grep -q 'capability-patterns\\.yml' && echo '{\"decision\": \"block\", \"reason\": \"capability-patterns.yml is CLI-owned orchestration logic. Do not modify without explicit human instruction.\"}' && exit 2 || exit 0"
           }
         ]
       }

.claude/skills/add-changelog-entry/SKILL.md

@@ -5,57 +5,27 @@ description: Add a changelog entry to UNRELEASED.md
 
 # /add-changelog-entry
 
-Automatically add a changelog entry to PROJECT_ROOT/UNRELEASED.md.
-
-## Instructions
-
-1. Check git diff or recent file modifications
-2. Determine the area from the file path:
-   - interfaces/cli/ → [CLI]
-   - core/ → [CORE]
-   - bundled/ → [BUNDLED]
-   - formatters/ → [FORMATTERS]
-   - README.md → [DOCS]
-   - CLAUDE.md, backbone.yml, .claude/, .reporails/ → [META]
-3. Determine the category:
-   - New files/content → Added
-   - Modified existing → Changed
-   - Marked as deprecated/obsolete → Deprecated
-   - Removed content → Removed
-   - Bug fixes → Fixed
-   - Security-related changes → Security
+Add a changelog entry to `UNRELEASED.md` based on recent changes.
+
+## Process
+
+1. Run `git diff` or check recent file modifications to determine what changed
+2. Determine the **area** from the file path:
+   - `src/reporails_cli/interfaces/cli/` → `[CLI]`
+   - `src/reporails_cli/core/` → `[CORE]`
+   - `src/reporails_cli/bundled/` → `[BUNDLED]`
+   - `src/reporails_cli/formatters/` → `[FORMATTERS]`
+   - `README.md`, `docs/` → `[DOCS]`
+   - `CLAUDE.md`, `.ails/backbone.yml`, `.claude/` → `[META]`
+3. Determine the **category**: Added (new files/content), Changed (modified existing), Deprecated, Removed, Fixed (bug fixes), Security
 4. Write a concise description (3-7 words)
-5. Append to UNRELEASED.md under the correct category section
-6. Create the category section if it doesn't exist
+5. Append to `UNRELEASED.md` under the correct `### [Category]` section — create the section if it doesn't exist
 
 ## Format
 
 ```markdown
 ### [Category]
-- [Area]: [Description]
-```
-
-## Categories
-
-Added, Changed, Deprecated, Removed, Fixed, Security
-
-## Areas
-
-- [CLI] – CLI interface (interfaces/cli/)
-- [CORE] – Core domain logic
-- [BUNDLED] – Bundled config (levels.yml, capability-patterns.yml)
-- [FORMATTERS] – Output formatters
-- [DOCS] – README, general documentation
-- [META] – CLAUDE.md, backbone.yml, repo structure
-
-## Example
-
-```markdown
-### Added
-- [CORE]: Semantic rule caching support
-
-### Changed
-- [FORMATTERS]: Updated compact output format
+- [Area]: Description
 ```
 
-Do not ask for confirmation. Just do it.
+Append directly without asking for confirmation.

.claudeignore

@@ -27,6 +27,11 @@ build/
 # IDE & editor
 .idea/
 
+# Research corpus — contains 4600+ CLAUDE.md and 6700+ .claude/rules/ files
+# from third-party repos. Without this exclusion, Claude Code loads them as
+# project instructions, contaminating every session.
+research/data/corpus/
+
 # Environment & secrets
 .env
 .env.local