Skip to content

v3.1.0: .devloop/ project-config convention

Choose a tag to compare

@one-kash one-kash released this 22 Aug 13:44
· 7 commits to main since this release

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.
  • Config discovery: each skill and agent resolves config as
    .devloop/<file> in the project, else generic mode. This is why a plugin
    install now works: the read-only cache holds the skills, but they read
    .devloop/ from the project. There is no copied-in PROJECT.md fallback
    (the old template files are removed); .devloop/ is the only
    project-config source.
  • validate.sh section 17: 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 16 now also rejects en dashes (not just em
    dashes), closing a gap in the standard-punctuation guard.
  • Plugin marketplaces: .claude-plugin/marketplace.json (Claude Code)
    and .agents/plugins/marketplace.json (Codex, its native catalog
    location) so devloop installs via
    /plugin marketplace add KashZod/devloop then
    /plugin install devloop@kashzod, and the codex plugin marketplace add
    / codex plugin add equivalents.

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 live in one place per stack under a top-level
    examples/<stack>/ (typescript-node, python, rust,
    android-kotlin), each holding a config.md and a domain.md; copy the
    closest directory to .devloop/. This replaces the split
    skills/spec/project-configs/ (domain) and
    skills/implement/project-configs/ (engineering) layout, and
    validate.sh now checks the examples in a single section (the former
    duplicate example-config check is removed).
  • /implement Phase 3 sizes the red-team half by diff size, the
    same way /plan sizes work (its Trivial / Small / Medium+ / Large
    table). A single-file change (or a trivial one with no new logic) runs
    one red-team in mode: both, unchanged from before. A broader,
    multi-file or cross-cutting diff (/plan Medium+ and Large) splits the
    red-team half into parallel mode: bugs and mode: cleanup runs so
    neither family crowds the other out. review-impl runs alongside in
    every case. Because red-team in mode: cleanup can apply fixes, the
    split invokes the cleanup run report-only, so all three concurrent
    agents only report and the parallel gate stays read-only. No new
    red-team mode was added; report-only is an invocation instruction
    inside cleanup mode.
  • validate.sh section 18 asserts the Phase 3 spawn stays
    size-adaptive (it names the mode: both, mode: bugs, mode: cleanup,
    and report-only markers), so a future edit can't silently revert to
    the fixed single-agent gate.

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.
  • Migrate an old PROJECT.md. The copied-in PROJECT.md fallback is
    gone; .devloop/ is the only project-config source. Split any old
    PROJECT.md into .devloop/config.md (engineering settings and paths)
    and .devloop/domain.md (domain knowledge), or copy the closest
    examples/<stack>/ directory as a starting point.

Fixed

  • Valid Claude Code manifest. .claude-plugin/plugin.json no longer
    enumerates skills/agents as arrays of objects, a shape the current
    schema rejects (claude plugin validate reported skills: Invalid input
    / agents: Invalid input). Claude Code auto-discovers skills/ and
    agents/, so the keys are dropped; the manifest now passes
    claude plugin validate --strict. The Claude manifest also gains
    repository and license, matching the Codex manifest.