Skip to content

AGENTS.md

Latest commit

 

History

History
87 lines (72 loc) · 4.07 KB

AGENTS.md

File metadata and controls

87 lines (72 loc) · 4.07 KB
Raw

Fallow public skills

This public repository owns portable end-user skills for the released Fallow product. It does not own Fallow maintainer workflows, private cloud knowledge, or public user documentation.

Start here

  • Skill content lives under fallow/skills/.
  • Each skill listed in source-lock.json follows the pinned public product contract. The lock has one entry per released Fallow skill. Each entry has a source root, a target root, and transforms.
  • cargo-fallow-source-lock.json pins the cargo-fallow skill from fallow-rs/cargo-fallow in the same shape. Run the check with --lock cargo-fallow-source-lock.json.
  • Skills that no lock lists, such as fallow-review, belong to this repository. The source contract check ignores them.
  • Agent-specific interface files may wrap a skill, but must not fork its authored instructions.
  • codex-app/ holds the source of the Fallow app for Codex: an MCP server and an MCP App that use the OpenAI MCP extensions. npm run build there writes the bundled output to fallow/codex-app/, which is committed because a plugin install runs no build step. CI rebuilds it and fails on a difference. Never edit fallow/codex-app/ by hand. See codex-app/README.md.
  • agent-view/ holds the TypeScript core that the Codex app and the Claude Code mod share: contracts, normalization, the view model of fallow inspect --cloud, and one fixture set. It imports no node: module. npm test in codex-app/ runs its tests.
  • claude-mod/ holds the source of the Fallow mod for Claude Code. It does not ship in the plugin yet, because Codex refuses the modules key in fallow/hooks/hooks.json. npm test there needs Claude Code; it runs claude plugin validate and claude plugin test on a staged copy.
  • The OpenAI directory submission stays skills-only. fallow/.codex-plugin/skills-only.json tells scripts/plugin_release.py which manifest fields and skills to leave out of that ZIP.
  • Public user guidance belongs in fallow-rs/docs.
  • Open-source maintainer workflows belong in fallow-rs/fallow.

Validation

Run:

node --test scripts/*.test.mjs
python3 -m unittest discover -s scripts -p 'test_*.py'
python3 scripts/validate_skill_frontmatter.py .
(cd codex-app && npm ci && npm run check)
(cd claude-mod && npm ci && npm run check && npm test)
FALLOW_SOURCE_DIR=/path/to/pinned/fallow node scripts/check-source-contract.mjs
CARGO_FALLOW_SOURCE_DIR=/path/to/pinned/cargo-fallow node scripts/check-source-contract.mjs --lock cargo-fallow-source-lock.json

The source contract check fails closed when the pinned source is absent, incorrect, or has drifted. Never copy private content or machine-local paths into this repository.

Keep skills concise, use progressive disclosure through direct references, and require a dry run before destructive Fallow operations.

Write for the reader

Write code comments, docs, commit messages, PR text, and changelog entries for a reader who did not see the session. Do not put the conversation, the prompt, discarded attempts, or the edit history into them. Describe the code as it is now. For a regression, state what breaks without the code, and link the issue. scripts/check-comment-quality.mjs blocks narration and history comments in the .githooks/pre-commit hook, in the Validate CI workflow, and in Claude edits.

Task completion

A task is done only when all of these are true:

  • every pull request of the task is merged to main, and the CI of the merged commit is green;
  • every companion pull request in another repository is merged;
  • every follow-up that the work found is fixed, or has a GitHub issue that the final report links;
  • the touched branches and worktrees are clean.

An open pull request is not done. This is also true while CI runs. A note in a scratch file or in the chat report does not track a follow-up. When a merge is blocked, report the pull request, the blocker, and the next action.

Sign each commit with git commit -S -s. The DCO check requires the sign-off.