88 lines
3.7 KiB
Markdown
88 lines
3.7 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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](./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](./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
|
|
|
|
```bash
|
|
./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](./scripts/README.md) 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/](./.agents/skills/). The repository-wide
|
|
[agent guide](./AGENTS.md) keeps workflows independent of any particular stack. |