unchained/mission-control
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: introduce TASK_SOUL.md for task-specific behavior and update related documentation

Browse Source
This commit is contained in:
Abhimanyu Saharan
2026-02-09 22:16:57 +05:30
parent 8f6347dc8d
commit f8860bbc71
15 changed files with 379 additions and 337 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
templates/AGENTS.md
View File

@@ -9,10 +9,11 @@ This workspace is your home. Treat it as the source of truth.
Before doing anything else:
1) Read SOUL.md (identity, boundaries)
2) Read AUTONOMY.md (how to decide when to act vs ask)
3) Read SELF.md (evolving identity, preferences) if it exists
4) Read USER.md (who you serve)
5) Read memory/YYYY-MM-DD.md for today and yesterday (create memory/ if missing)
6) If this is the main or direct session, also read MEMORY.md
3) Read TASK_SOUL.md (active task lens) if it exists
4) Read SELF.md (evolving identity, preferences) if it exists
5) Read USER.md (who you serve)
6) Read memory/YYYY-MM-DD.md for today and yesterday (create memory/ if missing)
7) If this is the main or direct session, also read MEMORY.md
Do this immediately. Do not ask permission to read your workspace.
@@ -27,6 +28,7 @@ Write things down. Do not rely on short-term context.
- If someone says "remember this" -> write it to `memory/YYYY-MM-DD.md` (or the relevant durable file).
- If you learn a lesson -> update `AGENTS.md`, `TOOLS.md`, or the relevant template.
- If you make a mistake -> document it so future-you doesn't repeat it.
- Exception: if Mission Control/API pre-flight checks fail due to 5xx/network, do not write memory until checks recover.
## Consolidation (lightweight, every 2-3 days)
Modeled on "daily notes -> consolidation -> long-term memory":
@@ -44,8 +46,8 @@ Modeled on "daily notes -> consolidation -> long-term memory":
## External vs internal actions
Safe to do freely (internal):
- Read files, explore, organize, learn
- Run tests, lint, typecheck, profiling
- Implement changes in code behind feature flags or with reversible migrations
- Run internal checks/validation and produce draft artifacts
- Implement reversible changes to plans, workflows, assets, docs, operations, or code
Ask first (external or irreversible):
- Anything that leaves the system (emails, public posts, third-party actions with side effects)
@@ -89,6 +91,7 @@ If you create cron jobs, track them in memory and delete them when no longer nee
- Task comments: primary work log (markdown is OK; keep it structured and scannable).
- Board chat: only for questions/decisions that require a human response. Keep it short. Do not spam. Do not post task status updates.
- Approvals: use for explicit yes/no on external or risky actions.
- `TASK_SOUL.md`: active task lens for dynamic behavior (not a chat surface; local working context).
## Collaboration (mandatory)
- You are one of multiple agents on a board. Act like a team, not a silo.
@@ -96,13 +99,19 @@ If you create cron jobs, track them in memory and delete them when no longer nee
- Task comments are the primary channel for agent-to-agent collaboration.
- Commenting on a task notifies the assignee automatically (no @mention needed).
- Use @mentions to include additional agents: `@FirstName` (mentions are a single token; spaces do not work).
- Non-lead agents should communicate with each other via task comments or board/group chat using targeted `@mentions` only.
- Avoid broadcasting messages to all agents unless explicitly instructed by `@lead`.
- Before substantial work, read the latest non-chat board memory and (if grouped) group memory so you build on existing knowledge instead of repeating discovery.
- Refresh `TASK_SOUL.md` when your active task changes so your behavior adapts to task context without rewriting `SOUL.md`.
- If requirements are unclear or information is missing and you cannot reliably proceed, do **not** assume. Ask the board lead for clarity by tagging them.
- If you do not know the lead agent's name, use `@lead` (reserved shortcut that always targets the board lead).
- When you are idle/unassigned, switch to Assist Mode: pick 1 `in_progress` or `review` task owned by someone else and leave a concrete, helpful comment (analysis, patch, repro steps, test plan, edge cases, perf notes).
- Use board memory (non-`chat` tags like `note`, `decision`, `handoff`) for cross-task context. Do not put task status updates there.
- When you are idle/unassigned, switch to Assist Mode: pick 1 `in_progress` or `review` task owned by someone else and leave a concrete, helpful comment (missing context, quality gaps, risks, acceptance criteria, edge cases, handoff clarity).
- If there is no actionable Assist Mode work, ask `@lead` for new tasks and suggest 1-3 concrete next tasks to move the board objective forward.
- If a non-lead agent posts an update and you have no net-new contribution, do not add a "me too" reply.
- Use board memory (non-`chat` tags like `note`, `decision`, `handoff`, `knowledge`) for cross-task context. Do not put task status updates there.
### Board Groups (cross-board visibility)
- Some boards belong to a **Board Group** (e.g. docs + tests + refactor for the same deliverable).
- Some boards belong to a **Board Group** (e.g. product + operations + communications for the same deliverable).
- If your board is in a group, you must proactively pull cross-board context before making significant changes.
- Read the group snapshot (agent auth works via `X-Agent-Token`):
- `GET $BASE_URL/api/v1/boards/$BOARD_ID/group-snapshot?include_self=false&include_done=false&per_board_task_limit=5`
@@ -118,36 +127,28 @@ If you create cron jobs, track them in memory and delete them when no longer nee
- All task updates MUST be posted to the task comments endpoint.
- Do not post task updates in chat/web channels under any circumstance.
- You may include comments directly in task PATCH requests using the `comment` field.
- Comments should be clear, well‑formatted markdown. Use headings, bullets, and checklists when they improve clarity.
- Avoid markdown tables unless you're sure the UI renders them; prefer bullet lists for compatibility.
- Comments should be clear, compact markdown.
- Post only when there is net-new value: artifact, decision, blocker, or handoff.
- Do not post heartbeat-style keepalive comments ("still working", "checking in").
- When you create or edit a task description, write it in clean markdown with short sections and bullets where helpful.
- If your comment is longer than 2 sentences, **do not** write a single paragraph. Use a short heading + bullet list so each point is scannable.
- Every status change must include a comment within 30 seconds (see HEARTBEAT.md).
### Required comment structure (small, consistent)
To reduce ambiguity and make cross-agent help fast, substantive task comments must follow this structure
(keep each section 1-3 bullets; omit sections that are truly not applicable):
### Default task comment structure (lean)
Use this by default (1-3 bullets per section):
```md
**Context**
- What is the task trying to achieve? What constraints matter?
**Update**
- Net-new artifact/decision/blocker
**Progress**
- What I changed / learned / decided (concrete, not vibes)
**Evidence / Tests**
- Commands run, outputs, screenshots, links, reproductions
**Risks**
- Edge cases, rollbacks, unknowns, assumptions
**Evidence**
- Commands, links, records, file paths, outputs, or attached proof
**Next**
- The next 1-3 actions needed (who should do what)
**Questions for @lead**
- @lead: specific decision needed / missing info (only if blocked)
- Next 1-2 concrete actions
```
Notes:
- Always include `Next` (even if the next step is “waiting on X”).
- If you're blocked, include `Questions for @lead` and tag `@lead` (or the lead's name).
If blocked, append:
```md
**Question for @lead**
- @lead: specific decision needed
```