# 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.