base/AGENTS.md

Repository Guide

This is a generic project starter, not an application scaffold. A project can be a novel, research, an event, software, or anything else. Read project-config.json for the project name, description, and any optional commands. Do not assume software, a language, platform, framework, package manager, architecture, or deployment target.

Structure

• README.md: getting started and configuration instructions.
• project-config.json: project identity and commands.
• docs/tasks.md: canonical task metadata and backlog.
• scripts/: Python and shell task-management tools.
• .agents/skills/: shared setup and task workflows.

Initial Setup

Use the initial-setup skill when cloning this template or reconfiguring a project. Ask the user for the project name, description, task prefix, project categories, and how they want to verify work. Ask about commands only when relevant; a writing project might use editorial review instead. Preserve existing work. Keep task prefixes and project categories in task frontmatter, not duplicated in the JSON configuration.

Working and Validation

• Verify work using the project's agreed criteria, whether editorial review, checklists, research validation, or automated tests.
• Run commands only when configured and appropriate. Empty commands means none are configured; do not invent a test, build, or development command.
• Using the bundled CLI tools requires Python 3.9+ and Bash or Zsh. Their tests use only the Python standard library. A project using this template need not use those tools or any programming language.
• When changing the bundled tooling, run python3 -m unittest discover -s scripts/tests -v.
• Follow existing patterns and avoid unrelated changes.
• Use relative links in repository documentation.
• Never commit credentials or local environment overrides.

Task Workflow

Use the task-management skill for task queries and edits, and execute-tasks for implementation of specified task IDs.

• Use the task CLI scripts; do not manually edit generated summary/enum tables.
• Read the configured prefix and statuses from task frontmatter. Numbers alone can be used when invoking task commands.
• Lifecycle: planning / triage / research -> ready -> in_progress -> testing -> done. Here testing means awaiting human verification, not necessarily software testing. Humans, not working agents, confirm done.
• Record human verification steps in docs/task-verification.md when a task moves to testing; create that document when first needed.
• When human verification succeeds, migrate those steps to docs/human-tests.md, creating it when needed.
• Commit only when requested. Include relevant task and verification changes, but do not stage unrelated edits or commit another person's work blindly.
• If the project maintains project-description documents, refresh their verification timestamps after major changes or 20 commits since their last update. Do not assume those optional documents already exist.