Skip to content

AGENTS.md

Latest commit

 

History

History
76 lines (58 loc) · 6.61 KB

AGENTS.md

File metadata and controls

76 lines (58 loc) · 6.61 KB
Raw

Develop Loop Skills — Agent Guide

Project overview

This repository packages Develop Loop: Bash CLI tooling, agent skills, templates, and evidence-verification scripts for an AI-native SDLC workflow. The published package is @develop-loop/skills; its executable is devloop.

Repository structure

  • .ai/skills/ is the source of truth for the orchestrator, seven phase skills, and traceability skill. Keep each skill self-contained with its adjacent reference.md when present.
  • bin/devloop dispatches the install, init, and doctor commands. Put command-specific behavior in bin/lib/{install,init,doctor}.sh; shared shell helpers belong in bin/lib/common.sh.
  • templates/ contains files copied by devloop init; keep template behavior aligned with the corresponding runtime scripts and skill contracts.
  • scripts/build-pack.sh generates the ignored pack/ distribution from VERSION, .ai/, templates/, and verifier scripts. Never treat pack/ as source.
  • scripts/loop-verify.sh implements L3 evidence checks; scripts/test-*.sh are executable regression suites.
  • .ai/config/profiles.yaml selects phases and human gates. .ai/contracts/evidence-policy.yaml is the authoritative artifact contract.
  • .ai/packages/<id>/, artifacts/<id>/, and traceability/<id>/ hold package state, phase artifacts, and package-level evidence. Preserve _template/ as the scaffold for new packages.
  • .github/workflows/ contains the CI definitions; docs/ contains project design, plans, requirements, and usage material.

Setup and verification

  • Require Bash; scripts declare #!/usr/bin/env bash and use Bash arrays and [[ ... ]].
  • Install/package dependencies with npm; no lockfile or other package manager is established.
  • Run the complete local suite with npm test.
  • Run targeted checks with ./scripts/test-build-pack.sh, ./scripts/test-devloop-cli.sh, or ./scripts/test-loop-verify.sh.
  • Run an L3 package check with ./scripts/loop-verify.sh [--enforce] <package_id>.
  • Build the distributable only with ./scripts/build-pack.sh; it recreates pack/.
  • Run ./bin/devloop doctor after changes to install/init behavior.

Architecture and dependency rules

  • Change skill behavior in .ai/skills/; update scripts/build-pack.sh only when the distribution mapping changes.
  • Keep bin/devloop as a thin dispatcher. Source command libraries there rather than duplicating command parsing or pack discovery.
  • Use DEVLOOP_PKG_ROOT and helpers from bin/lib/common.sh for package-root and pack-path resolution; preserve DEVLOOP_HOME as the testable home-directory override.
  • Keep .ai/config/profiles.yaml and .ai/contracts/evidence-policy.yaml consistent: profiles select a flow, while the evidence policy defines required artifacts.
  • When changing a template-managed file, update the source template and the tests that validate devloop init/--upgrade; do not edit generated fixture output.
  • Keep L2 gate decisions in .ai/packages/<id>/gates/; phase skills create evidence but do not write final gate PASS decisions.
  • Preserve package audit links: gates must bind exact artifacts, and package evidence must include traceability/<id>/matrix.md and package-evidence-index.md.
  • For structural code questions, use CodeGraph when available; use literal search only for text/content questions. If the index is absent, request approval before initializing it.

Coding standards

  • Write Bash scripts with set -euo pipefail, a repository-root calculation, quoted expansions, and explicit [[ ... ]] checks, matching bin/ and scripts/.
  • Fail fast with an ERROR: or FAIL: message and a non-zero exit; keep successful test output in the existing PASS: style.
  • Keep CLI usage and command behavior synchronized across bin/devloop, README.md, .ai/skills/devloop/SKILL.md, and templates/AGENTS.md when a user-facing command changes.
  • Use package IDs as directory keys; do not rename or delete historical gate attempts when evidence changes.
  • Do not hand-edit pack/, copy source skills into pack/, or commit generated pack/ output.
  • Do not add a new runtime/package manager, formatter, linter, or CI check without an explicit repository decision; none is established here.

Testing requirements

  • Add or update the matching executable regression script for every changed CLI, build, template, or verifier behavior.
  • For build/distribution changes, run ./scripts/test-build-pack.sh and ./scripts/test-devloop-cli.sh.
  • For evidence-policy or verifier changes, run ./scripts/test-loop-verify.sh and the relevant ./scripts/loop-verify.sh --enforce <package_id> check.
  • Treat scripts/test-loop-verify.sh as exclusive: it temporarily rewrites .ai/contracts/evidence-policy.yaml and restores it through its trap.
  • Record any deliberately unrun relevant check and its reason in the change handoff.

Security rules

Not established in this repository: no secret-management, authentication, or dependency-security policy/configuration was found. Do not introduce secret-handling or security claims without an explicit project requirement.

Agent workflow and domain constraints

  • Use /devloop start <id> to create and classify a package, then /devloop run <id> to drive its profile. Use /devloop continue <id> only to resume persisted run control state.
  • Read .ai/packages/<id>/package.yaml, its gates, and the active profile before advancing a package. Re-read on disk after each phase.
  • Stop after a passing human-gated phase; do not start the next phase until the user invokes /devloop continue <id>.
  • Use routine, standard, or high_risk exactly as configured. High-risk work requires the policy's additional review evidence, including security-review.md for code review.
  • Keep implementation within archived requirements, design, and test-plan inputs required by the active profile; record every touched path in changed-files.md.
  • Use /devloop gate <id> <phase> for authoritative L2 decisions. A passing gate cannot contain unresolved blocking findings or unchecked required evidence.

PR checklist

  • Only intended source, template, test, documentation, and evidence files are staged; generated pack/ is excluded.
  • VERSION and package.json versions match when publishing a release.
  • User-facing command changes are synchronized across CLI, README, skill, template, and tests.
  • Relevant targeted tests pass; run npm test for changes spanning the distributable or CLI.
  • Relevant L3 verification passes for changed package evidence.
  • CI impact is checked: build-pack.yml covers pack inputs, and loop-verify.yml covers .ai/, artifacts, traceability, and the verifier.