1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
|
# Create task
Use with `00-context.md`. Project name and global rules apply. New tasks get `+agent` so they are agent-managed. When a new task depends on existing tasks, add those dependencies inline during creation with `depends:<id>,...`.
## Rules for new tasks
- **When creating a new task, always check whether the new task depends on other (existing) tasks.** If it does, add those dependencies inline with `depends:<id>,...` while creating the task.
- **Create tasks in smaller chunks that fit into the context window.** Break work into multiple tasks so that each task's scope, description, and required context (refs, files, docs) can fit in one context window when the agent works on it with a fresh context. Do not create single tasks that would require more context than available.
- **Every task MUST have at least one tag** for sub-project/feature/area (e.g. `+integrationtests`, `+flamegraph`, `+bpf`, `+cli`, `+refactor`, `+bugfix`).
- **After creating a task, add annotation** — one with the agent workflow reminder:
```
ask annotate <id> "Agent workflow: load the agent-task-management skill as instructions only, not as a shell command. Use only normal ask subcommand syntax. Also load and apply: (1) the best-practices skill for the programming language used in the project, (2) solid-principles. When all tests and sub-agent reviews pass, commit and automatically progress to the next ready task."
```
- **Include references to all context required** to work on the task. So that work can be done with a fresh context, every task must list or link everything needed: relevant files, docs, specs, other tasks, or project guidelines (e.g. paths, doc links, `AGENTS.md`, `README` sections). Put these in the task description or in an initial annotation so that an agent starting with no prior conversation has everything they need in the task itself.
- When tasks refer to other tasks in free text (annotations, descriptions, docs, or commit messages).
## Add a task
`ask add` already injects `project:<name> +agent`, so only add the extra feature tag(s), optional priority, optional `depends:` modifier, and description.
**Each part must be a separate shell argument — never quote tag and description together:**
```bash
ask add +<tag> "Description"
ask add priority:H +<tag> "Description"
ask add priority:M +<tag> "Description"
ask add +<tag> depends:<id1>,<id2> "Description"
```
Do NOT do this (causes tag/priority to appear in the description instead of being applied):
```bash
ask add "+<tag> Description" # wrong: tag and desc in one quoted string
ask add "+<tag> -p M Description" # wrong: everything in one quoted arg
```
`ask add` prints `created task <alias-id>`. Reuse that alias ID directly for follow-up commands:
```bash
id=$(ask add +<tag> "Description" | sed -n 's/^created task //p')
ask annotate "$id" "Agent workflow: load the agent-task-management skill as instructions only, not as a shell command. Never run ask agent-task-management ... or other natural-language ask commands. Use only normal ask subcommand syntax. Also load and apply: (1) the best-practices skill for the programming language used in the project, (2) solid-principles, and (3) beyond-solid-principles. When all tests and sub-agent reviews pass, commit and automatically progress to the next ready task."
```
## With dependency
Add dependencies inline during task creation:
```bash
id=$(ask add +<tag> depends:<dep-id> "Description" | sed -n 's/^created task //p')
```
Multiple dependencies:
```bash
id=$(ask add +<tag> depends:<dep-id1>,<dep-id2> "Description" | sed -n 's/^created task //p')
```
After adding (with or without dependency), run the same annotations using that alias ID directly.
## Conventions
- **Keep tasks small:** each task should be a chunk that fits in the context window (description + refs + work to do). Split large efforts into multiple dependent tasks.
- Pick or create a meaningful tag for the sub-project or feature.
- **Always check for dependencies:** before adding a task, determine if it depends on other tasks in the project; if so, add `depends:<id>,...` during `ask add`.
- Add dependencies when one task must complete before another can start.
- When creating a task, add references to all required context (files, docs, specs) so the task is self-contained for fresh-context work.
|
