base/README.md

Getting Started

1. Clone this repository and enter the clone directory.

2. No project language or platform is prescribed. To use the optional bundled task CLI tools, install Python 3.9+ and use Bash or Zsh. The Markdown tracker and agent skills can also be used without those tools.

3. In your coding assistant, request "Run initial setup for this repository" or invoke /initial-setup. The shared skill asks for your project details and creates your configuration without assuming software or an application stack. A novel, research project, or event plan is equally valid.

4. If using the CLI tools, validate the tooling and inspect the sample task:

   python3 -m unittest discover -s scripts/tests -v
   ./scripts/get-task EX-001
   ./scripts/get-tasks --all
   

   After choosing a different prefix, use your new ID or simply ./scripts/get-task 1.

5. Optionally load task commands and aliases into your shell:

   source ./scripts/env.sh
   

Example Project

A generic project starter with task tracking and reusable agent workflows. It includes one sample task, not an application or deployment stack. The project's subject, language, platform, and way of verifying work are unspecified.

Configuration

project-config.json is the shared configuration for the project name, description, and optional named commands. The triage and research helpers read it when building agent prompts. Commands are guidance, not automatically executed by those helpers. The sample's commands is empty. Add commands only if relevant, for example a manuscript word-count command or a software test command. Human review needs no command.

docs/tasks.md owns task configuration:

• task-id-prefix: EX in this example.
• projects: labels, keys, and repository-relative paths. The sample key is example-project.
• task-statuses, task-types, and optional epics / subprojects.

For manual setup, edit the JSON configuration and task frontmatter, then run ./scripts/update-tasks. It regenerates tables and migrates task IDs and internal links when the prefix changes. Preserve numeric IDs and existing tasks. If changing project keys, also update their task anchor data-project attributes before synchronizing.

TASK_ID_PREFIX overrides frontmatter; without either, scripts default to EX. TASKS_FILE or -f /path/to/tasks.md selects another tracker. Keep machine-specific overrides in ignored scripts/env.sh.local or .env, which are sourced by the optional environment helper. These must contain trusted shell syntax, not arbitrary dotenv syntax.

Task Commands

./scripts/add-task "Outline the first deliverable" --project example-project --type task --status triage
./scripts/get-task 1 --json
./scripts/update-task 1 --status ready
./scripts/work-on-task 1 --start
./scripts/update-task 1 --status testing --check-all
./scripts/update-tasks

Working agents move completed work to testing; humans verify it before moving it to done. testing means review/verification, not necessarily automated software testing.

triage and research optionally launch Hermes or Antigravity. Those external CLIs are not required for the core task commands or tests. See the script guide for options.

Shared Agent Skills

• initial-setup: interview the user and configure a fresh clone.
• task-management: query, add, update, and synchronize tasks.
• execute-tasks: implement specified tasks sequentially and record checks.

These live in .agents/skills/. The repository-wide agent guide keeps workflows independent of any particular stack.