61 lines
3.1 KiB
Markdown
61 lines
3.1 KiB
Markdown
# 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](./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](./README.md): getting started and configuration instructions.
|
|
- [project-config.json](./project-config.json): project identity and commands.
|
|
- [docs/tasks.md](./docs/tasks.md): canonical task metadata and backlog.
|
|
- [scripts/](./scripts/): Python and shell task-management tools.
|
|
- [.agents/skills/](./.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.
|