v3.1.0: .devloop/ project-config convention

Introduce a single project-local home for devloop's per-project files:
.devloop/. Fixes config discovery under a plugin install (skills live in a
read-only shared cache where a PROJECT.md beside SKILL.md never resolves in
the user's project) and gives trackers a stable home outside docs/.

- .devloop/config.md: engineering config + operational paths (spec and
  tracker directories, commit conventions), read by /plan, /implement, the
  three review agents, and /spec (spec-directory setting).
- .devloop/domain.md: pure domain knowledge, read by /spec.
- .devloop/trackers/: default tracker home (was docs/).
- Two-tier discovery: .devloop/<file> -> copied-in PROJECT.md template ->
  generic mode.
- Harness-agnostic project-rules references throughout (CLAUDE.md/AGENTS.md).
- validate.sh: section 18 requires each skill and review agent to name the
  .devloop/ home; section 17 now also rejects en dashes.
- Manifests bumped to 3.1.0; Claude manifest gains repository + license.

Author: one-kash

.claude-plugin/plugin.json

@@ -1,9 +1,11 @@
 {
   "name": "devloop",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Spec, plan, implement, review: a test-driven development loop for AI coding agents. Three commands map to three gates, one per command (plus a convergence back-edge where /implement re-runs the plan gate): /spec (WHAT, spec validation), /plan (HOW, plan review), /implement (BUILD, conformance + adversarial red-team review).",
   "keywords": ["tdd", "specification", "code-review", "red-team", "workflow", "quality"],
   "homepage": "https://github.com/KashZod/devloop",
+  "repository": "https://github.com/KashZod/devloop",
+  "license": "Apache-2.0",
   "author": {
     "name": "KashZod"
   },

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "devloop",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Spec, plan, implement, review: a test-driven development loop for AI coding agents. Three commands map to three gates, one per command (plus a convergence back-edge where /implement re-runs the plan gate): /spec (WHAT, spec validation), /plan (HOW, plan review), /implement (BUILD, conformance + adversarial red-team review).",
   "author": {
     "name": "KashZod"

.gitignore

@@ -11,6 +11,9 @@
 # Working docs
 docs/
 
+# devloop's own dev-time state (this repo dogfoods the convention it ships)
+.devloop/
+
 # Node (if users clone into a node project)
 node_modules/
 

CHANGELOG.md

@@ -1,5 +1,61 @@
 # Changelog
 
+## 3.1.0
+
+A single project-local home for devloop's per-project files: `.devloop/`.
+This fixes config discovery under a plugin install (where the skills live
+in a read-only shared cache and a `PROJECT.md` beside `SKILL.md` never
+resolves in the user's project) and gives trackers a stable home outside
+`docs/`.
+
+### Added
+- **`.devloop/` convention**: skills and agents read project config from
+  `.devloop/` in the project root:
+  - `config.md`, engineering config (build/test/lint commands, architecture
+    rules, standards, blindspots, commit conventions, and the spec/tracker
+    directory settings), read by `/plan`, `/implement`, `review-plan`,
+    `review-impl`, `red-team`, and `/spec` (for the spec-directory setting).
+  - `domain.md`, pure domain knowledge (domain context, architecture
+    overview, domain-specific concerns, existing patterns, quality
+    standards), read by `/spec`.
+  - `trackers/`, home for `impl-tracker-<feature>.json`, written by `/plan`.
+- **Two-tier discovery**: each skill and agent resolves config as
+  `.devloop/<file>` in the project, then the copied-in `PROJECT.md` template
+  that ships with the skills, then generic mode. This is why a plugin install
+  now works: the read-only cache holds the skills, but they read `.devloop/`
+  from the project.
+- **`validate.sh` section 18**: fails if a core file reintroduces the
+  plugin-cache config pointer ("plugin's skill directory") and requires each
+  skill and review agent to name the `.devloop/` home.
+- **`validate.sh` section 17** now also rejects en dashes (not just em
+  dashes), closing a gap in the standard-punctuation guard.
+
+### Changed
+- **Config ownership**: `config.md` owns the operational paths (spec
+  directory, tracker directory) alongside the engineering settings;
+  `domain.md` is now purely domain knowledge. Commit conventions live only
+  in `config.md` (read by the skills that commit). `/spec` reads its output
+  path from `config.md` and its domain context from `domain.md`.
+- **Tracker home**: `/plan` writes trackers to `.devloop/trackers/` by
+  default (was `docs/`); `/implement`, `review-plan`, and `review-impl`
+  look there.
+- **Example configs** now label their destination: the
+  `implement/project-configs/` examples are headed as `.devloop/config.md`
+  examples, the `spec/project-configs/` examples as `.devloop/domain.md`
+  examples (the directory names are unchanged).
+
+### Migration
+- **Move in-flight trackers.** Trackers previously written under `docs/`
+  now live in `.devloop/trackers/`, and this release drops the `docs/`
+  read-fallback. Move any existing `docs/impl-tracker-*.json` into
+  `.devloop/trackers/`, or pass an explicit tracker path when invoking
+  `/implement` or the review agents.
+- **Split an old `PROJECT.md`.** If you relied on a copied-in `PROJECT.md`,
+  split it into `.devloop/config.md` (engineering settings and paths) and
+  `.devloop/domain.md` (domain knowledge). The copied-in `PROJECT.md`
+  templates still work as the fallback, but `.devloop/` takes precedence and
+  is what a plugin install reads.
+
 ## 3.0.0
 
 Three-command split, a harness-agnostic rewrite, and a de-overlapped

README.md

@@ -28,12 +28,10 @@ red-team       Independent agent hunts bugs + cleanups in the diff
                  via the review-plan agent in-session, then resumes
 ```
 
-Three commands map to three gates, one gate per command: `/spec` (WHAT,
-spec validation), `/plan` (HOW, plan review), `/implement` (BUILD,
-conformance + red-team review). The one exception is the convergence
-back-edge below, where `/implement` re-runs the plan-review gate
-in-session. The three review agents run in isolated context, they didn't
-write the plan or code, so they evaluate honestly.
+Three commands, three gates, one per command: `/spec` (WHAT), `/plan`
+(HOW), `/implement` (BUILD). The review agents run in a context that did
+not write the plan or code, so their verdict is independent, not the author
+grading itself.
 
 ## Why not just prompt the AI?
 
@@ -54,18 +52,14 @@ everything *around* the code:
 - **Prompts do not compose or persist.** They live in your head and drift
   from run to run and project to project.
 
-devloop exists to close exactly these gaps: it separates WHAT / HOW /
-BUILD into three gated steps, runs review in a context that did not write
-the code, persists a tracker so work survives resets, makes every gate an
+devloop closes these gaps: it separates WHAT / HOW / BUILD into three
+gated steps, runs review in a context that did not write the code,
+persists a tracker so work survives resets, makes every gate an
 evidence-backed hard-stop, and ships as a versioned artifact that behaves
-the same across projects and harnesses. The next section is how each piece
-pays off; [How the loop works](#how-the-loop-works) is the mechanics.
+the same across projects and harnesses.
 
-## Why This Workflow
+## What the review layer adds
 
-- **The reviewer didn't write the code.** Review agents spawn in a
-  fresh context, separate from the author, so author-evaluator bias is
-  cut by the setup, not just by asking the reviewer to be objective.
 - **Design bugs are caught before coding starts.** An 8-point plan
   review runs before any code is written. Fixing a wrong abstraction
   in a plan costs minutes; in code, hours.
@@ -83,8 +77,6 @@ pays off; [How the loop works](#how-the-loop-works) is the mechanics.
   under-report), then runs a verify pass that keeps only
   CONFIRMED/PLAUSIBLE findings and drops the rest, trading a noisier
   find phase for higher recall without shipping the false positives.
-- **Work survives context resets.** A JSON tracker tells a new session
-  exactly where to pick up.
 
 ## How the loop works
 
@@ -106,8 +98,8 @@ agent would tie the loop to a single harness.
 
 The gates depend on spawning those agents. On a harness with no subagent
 capability at all, each gate degrades to an in-context self-check and
-loses the author-evaluator isolation that is the point, the skills say so
-at each gate rather than pretending the guarantee still holds.
+loses the author-evaluator isolation; the skills say so at each gate
+rather than pretending the guarantee still holds.
 
 ## What's Included
 
@@ -134,9 +126,10 @@ in a fresh context and runs a two-family review:
 - **Correctness** (5 angles): line-by-line diff scan, removed-behavior
   auditor, cross-file caller/callee tracer, language-pitfall
   specialist, wrapper/proxy correctness.
-- **Cleanup** (4 angles): reuse, simplification, efficiency, altitude
- , plus a conventions angle that reads the project's own `CLAUDE.md` /
-  `PROJECT.md` at runtime and only flags rules it can quote.
+- **Cleanup** (4 angles): reuse, simplification, efficiency, altitude,
+  plus a conventions angle that reads the project's own rules file
+  (`CLAUDE.md`/`AGENTS.md`) and `.devloop/config.md` at runtime and only
+  flags rules it can quote.
 
 It then **verifies** each candidate (recall-biased: PLAUSIBLE by
 default, REFUTED only when the code proves it) and **sweeps** once more
@@ -155,10 +148,6 @@ Use the red-team agent in mode: both to review the changed files
 Use the red-team agent in mode: cleanup to tidy the changed files
 ```
 
-`red-team` reads no project assumptions of its own, it discovers
-standards from the project's `CLAUDE.md` / `PROJECT.md` each run, so
-the same agent works across projects.
-
 ## Install
 
 **Claude Code.** Copy `skills/` and `agents/` into your project's
@@ -174,27 +163,42 @@ ride along as prompt files: the skills spawn them as subagents where the
 harness supports delegation, and otherwise degrade to the in-context
 self-check the gates already document.
 
-Then give the loop project context. There are **two** `PROJECT.md`
-templates:
+Then give the loop project context in a `.devloop/` directory at your
+project root:
 
-- `skills/implement/PROJECT.md`, the engineering config, build/test/lint
-  commands, architecture rules, standards, and blindspots. Read by
-  `/plan`, `/implement`, `review-plan`, `review-impl`, and `red-team`.
-  `/plan` and `/implement` share this one config; there is no separate
-  plan config.
-- `skills/spec/PROJECT.md`, domain context, architecture overview, and
-  domain-specific concerns. Read by `/spec`.
+```
+.devloop/
+  config.md    # engineering: build/test/lint, architecture, standards,
+               #   blindspots, commit conventions, and the spec/tracker
+               #   directory settings. Read by /plan, /implement,
+               #   review-plan, review-impl, red-team, and /spec (which
+               #   reads the spec-directory setting from here).
+  domain.md    # domain context, architecture overview, domain-specific
+               #   concerns. Read by /spec.
+  trackers/    # impl-tracker-<feature>.json, written by /plan
+```
 
-Fill in both (each is a template of `YOUR_*_HERE` placeholders). The
-fastest start is to copy the closest example from
+Each skill and agent resolves its config in this order: `.devloop/<file>`
+in your project first, then the copied-in `PROJECT.md` template, then
+generic mode if neither exists (the loop still runs, with less
+project-specific insight). The `PROJECT.md` template is the fallback only
+when devloop is copied into your project rather than installed as a plugin;
+the engineering config ships as the implement skill's `PROJECT.md`, the
+domain config as the spec skill's. This is why a plugin install works: the
+skills live in a read-only cache, but they read `.devloop/` from your
+project, not the cache.
+
+The fastest start is to copy the closest example to `.devloop/config.md`
+from
 [`skills/implement/project-configs/`](skills/implement/project-configs/)
-and [`skills/spec/project-configs/`](skills/spec/project-configs/),
-ready-made configs for Node/TypeScript, Python, Rust, and
-Android/Kotlin. Both skills run fine with no `PROJECT.md` (generic
-defaults apply), just with less project-specific insight.
+and to `.devloop/domain.md` from
+[`skills/spec/project-configs/`](skills/spec/project-configs/),
+ready-made configs for Node/TypeScript, Python, Rust, and Android/Kotlin.
+Each is a template of `YOUR_*_HERE` placeholders; fill them in.
 
-**Installing as a plugin?** Your filled-in `PROJECT.md` belongs in your
-own project, not in the read-only plugin directory.
+**Commit `config.md` and `domain.md`** so the whole team shares one
+context. `.devloop/trackers/` holds in-progress work; commit it for
+cross-machine resumability or gitignore it, your call.
 
 ## Optional: proof that the check actually ran (rung)
 
@@ -206,10 +210,9 @@ that last gap: it records whether a check drove the real surface (not just
 an isolated test or a reading of the code) and whether an independent
 context ran it, then gates on that record deterministically.
 
-It maps cleanly onto devloop. rung's author-vs-independent context is the
-same author-evaluator split the review agents enforce, and its rung-level
-(drove the real surface vs isolated test) hardens the TDD green step into
-a re-checkable artifact instead of a self-report.
+rung's author-vs-independent split is the same one devloop's review agents
+enforce, and its check-level record hardens the TDD green step into a
+re-checkable artifact instead of a self-report.
 
 This is optional and unbundled by design. devloop ships only markdown and
 a bash validator, with no runtime dependencies; rung is a separate
@@ -218,6 +221,18 @@ regression run in `rung run --rung 1` and gate CI on `rung gate`
 (exit `0` is the only pass). Keep it out of the core loop unless you want
 CI-enforceable proof that the checks were real.
 
+## Related Work
+
+[GitHub Spec Kit](https://github.com/github/spec-kit) is a spec-driven
+development toolkit in the same space, with a comparable specify -> plan ->
+tasks -> implement flow across several coding agents. devloop's `/spec ->
+/plan -> /implement` shape covers similar ground; where it differs is the
+review layer: three independent agents (`review-plan`, `review-impl`,
+`red-team`) run in author-isolated context as hard gates between the
+phases, and the loop is TDD-first with a JSON tracker that survives context
+resets. For the broader spec-driven tooling ecosystem, start with Spec Kit;
+for the gated, review-heavy loop, devloop is narrower by design.
+
 ## License
 
 Apache-2.0. See [LICENSE](LICENSE).

agents/red-team.md

@@ -168,12 +168,13 @@ special cases.
 
 ### Conventions angle (all modes, run when project rules exist)
 
-Find the guidance files that govern the changed code: the repo-root
-`CLAUDE.md`, plus any `CLAUDE.md`/`CLAUDE.local.md` in a directory that is an
-ancestor of a changed file (a directory's `CLAUDE.md` applies only to files
-at or below it), plus `PROJECT.md` in this plugin's skill directory if the
-task points at one. Read each that exists, then check the diff for clear
-violations of the rules they state.
+Find the guidance files that govern the changed code: the repo-root project
+rules file (`CLAUDE.md` or `AGENTS.md`), plus any such file (including local
+overrides) in a directory that is an ancestor of a changed file (it applies
+only to files at or below it), plus `.devloop/config.md` in the project root (or the
+copied-in `PROJECT.md` engineering template shipped with the implement skill,
+when devloop is copied in rather than installed as a plugin). Read each that
+exists, then check the diff for clear violations of the rules they state.
 
 Only flag a violation when you can quote the exact rule and the exact line
 that breaks it, no style preferences, no vague "spirit of the doc"
@@ -182,7 +183,7 @@ governing file applies, return nothing for this angle.
 
 **This is where project-specific standards enter, at runtime, from the
 project's own files.** Do not carry project assumptions into this agent;
-read `CLAUDE.md`/`PROJECT.md` fresh each run and let them define what a
+read the project rules file (`CLAUDE.md`/`AGENTS.md`) and `.devloop/config.md` fresh each run and let them define what a
 violation is (architecture layers, test-double policy, forbidden vocabulary,
 i18n rules, whatever the project states).
 
@@ -242,7 +243,7 @@ empty sweep, do not pad.
 
 ### `bugs` / `both` mode, report findings
 
-Report the surviving findings (CONFIRMED + PLAUSIBLE from Phases 2–3), ranked
+Report the surviving findings (CONFIRMED + PLAUSIBLE from Phases 2-3), ranked
 most-severe first, correctness before cleanup. For each:
 
 ```

agents/review-impl.md

@@ -11,8 +11,7 @@ effort: high
 You are an independent conformance reviewer. Your job is to verify that
 the implementation matches the plan, every acceptance criterion is met
 and proven by a test, and no regressions were introduced. You did NOT
-write this code, you are reviewing someone else's work. Be thorough,
-specific, and honest.
+write this code, you are reviewing someone else's work.
 
 ## Division of Labor (read this first)
 
@@ -24,8 +23,8 @@ with the `red-team` agent, which is the **correctness gate**.
 
 - adversarial correctness bug hunting (inputs, state, timing, platform)
 - robustness and blindspot hunting (edge cases, resource cleanup, races)
-- standards and architecture violations (when no `PROJECT.md`/`CLAUDE.md`
-  exists, `red-team`'s conventions angle has nothing to quote, so
+- standards and architecture violations (when no `.devloop/config.md` or
+  project rules file exists, `red-team`'s conventions angle has nothing to quote, so
   `/implement` Phase 3 covers these with a self-check, they are not
   silently dropped)
 - dead code, reuse, simplification, efficiency, altitude cleanup
@@ -44,8 +43,9 @@ You will receive:
 - The **project root** (for reading implementation and tests)
 - Optionally, a list of **changed files** or a git diff range
 
-If no plan path is given, look for the most recent
-`impl-tracker-*.json` in `docs/`. If no changed files are given, derive
+If no plan path is given, look for the most recent `impl-tracker-*.json` in
+the tracker directory (the tracker-directory setting in `.devloop/config.md`,
+default `.devloop/trackers/`). If no changed files are given, derive
 them from the tracker's `files_create` and `files_modify` arrays across
 all chunks.
 
@@ -55,9 +55,9 @@ all chunks.
 
 Read these files (skip any that don't exist):
 - The plan/tracker document
-- `CLAUDE.md` (project rules and architecture)
-- The project's engineering `PROJECT.md` (build commands, standards)
-- The spec the tracker names in `spec_doc` (or, if absent, any spec in the configured spec directory: `PROJECT.md`, default `docs/specs/`)
+- The project rules file, `CLAUDE.md` or `AGENTS.md` (project rules and architecture)
+- The project's engineering config `.devloop/config.md` (build commands, standards; the copied-in `PROJECT.md` engineering template shipped with the implement skill is the fallback)
+- The spec the tracker names in `spec_doc` (or, if absent, any spec in the configured spec directory: the spec-directory setting in `.devloop/config.md`, default `docs/specs/`)
 
 ### Step 2: Build the Review Map
 
@@ -163,8 +163,8 @@ is misapplied, FAIL this criterion and recommend extracting the holder.
 Did the implementation break existing functionality, and does it build?
 
 **How to check:**
-- Run the full test suite (see `PROJECT.md` for command)
-- Run the build/compile command (see `PROJECT.md` for command)
+- Run the full test suite (see `.devloop/config.md` for command)
+- Run the build/compile command (see `.devloop/config.md` for command)
 - Compare test count to before (check git log for prior test counts if available)
 - Note new warnings in build output
 
@@ -253,7 +253,7 @@ WARN, not FAIL, unless the plan's `tdd` promised a test for them.
 ## Rules
 
 - **Run the tests.** Don't just read them, execute the project's test
-  and build commands (see `PROJECT.md`). Report actual results, not assumptions.
+  and build commands (see `.devloop/config.md`). Report actual results, not assumptions.
 - **Read the actual code.** Don't trust the plan's description of what
   was implemented. Read every file in the tracker's file lists.
 - **Quote your evidence.** Every criterion state and every WARN/FAIL