teamharness-project-management

Project Management

Use this skill when maintaining durable project state.

A project owns the plan, context, dependencies, and accepted progress. Keep the project plan separate from individual task execution logs.

Only advance a dependency after the Leader accepts the submitted result. Do not use this skill for ordinary direct replies or lightweight one-off actions.

Scope

Use this skill when acting as Leader for:

• projectflow calls
• project creation
• quick single-task project creation
• DAG planning
• Loop planning
• ready-node resolution
• Loop iteration recording
• accepting checked Worker results into project progress
• project-level status reports

For Project Work, use teamharness-team-coordination first to decide task boundaries. If no task room exists yet, use teamharness-roomflow and teamharness-communication before this skill. Use teamharness-task-delegation for individual task specs, assignment messages, and Worker result checks.

Project Files

Project files live under:

shared/projects/{project-id}/

TeamHarness writes CoPaw-compatible task runtime files:

shared/projects/{project-id}/meta.json
shared/projects/{project-id}/plan.md

Write a final project result, when needed, to:

shared/projects/{project-id}/result.md

The Leader owns this project result file. Build it from accepted project state and accepted task deliverables; do not ask Workers to write or submit it as a task deliverable.

Use projectflow to change meta.json and plan.md; do not hand-edit project state unless a tool failure leaves no safe alternative.

ID Rules

Use safe IDs only:

[A-Za-z0-9][A-Za-z0-9._-]*

Do not use colons, slashes, spaces, or Matrix IDs as project or task IDs.

Suggested formats:

projectId: {short-description}-YYYYMMDD-HHMMSS
taskId: {projectId}-{seq}

If a user or test provides explicit IDs, preserve them when they are already safe.

Tool Payload Rule

When calling projectflow, pass payload as a JSON object, not as a serialized JSON string.

Create Project

Create the project before planning tasks:

{
  "action": "create_project",
  "payload": {
    "projectId": "demo-project-001",
    "title": "Demo Project",
    "source": "dingtalk",
    "requester": "dingtalk:sender_001:aaaaaaaa",
    "replyRoute": {
      "channel": "dingtalk",
      "targetUser": "sender_001",
      "targetSession": "aaaaaaaa"
    }
  }
}

This creates meta.json and plan.md.

If projectId is omitted, TeamHarness derives one from title plus timestamp. If the generated ID already exists, TeamHarness appends a numeric suffix. Explicit projectId collisions are rejected.

Use replyRoute when the requester came from a runtime channel that may need a cross-session final report. channel, targetUser, and targetSession must come from the current message/session metadata or a trusted runtime query. Do not guess them.

For Project Work that should proceed in a dedicated task room, do not call create_project in the requester/source session. Use teamharness-communication to send a PROJECT_REQUESTED self-trigger from the current requester/source session to the same Leader in the target Matrix task room first. After the task-room Leader session wakes up, call create_project there and preserve the original requester route from the visible PROJECT_REQUESTED request: keep the original source, requester, sourceRoomId, and replyRoute so final reports can return to the DingTalk group, Matrix DM, or other source room that made the request. Do not invent missing replyRoute values from requester names or prose.

For DingTalk requester compatibility, requester may use dingtalk:{user_id}:{session_id}; TeamHarness derives reply_route from that value when replyRoute is not provided.

Create Quick Project

Use create_quick_project only after Quick Task mode is selected and the Leader is in the Matrix Task room that received the task request message. It is a shortcut for:

create_project + plan single-node DAG + assigned task spec

Do not call this in the requester/source session. If the current session is still a DingTalk group, Matrix DM, Team room, or other source room, return to TEAMS.md: create or reuse the task room with teamharness-roomflow, hand the request to that room with teamharness-communication, and stop in the source session.

Before calling this action in the Task room:

1. Use the current Matrix task room as roomId.
2. Preserve the original source, requester, sourceRoomId, and replyRoute from the task request message. Do not guess route values.
3. Choose the one Worker owner from the team roster.
4. Write a bounded task spec that includes the completion report instruction from teamharness-task-delegation.

teamharness-roomflow owns task-room creation, project-scoped reuse, source metadata capture, and Worker invites. This skill only creates durable project and task state after the Task room is already selected.

Example:

{
  "action": "create_quick_project",
  "payload": {
    "title": "Write readiness note",
    "source": "matrix",
    "requester": "@admin:matrix.local",
    "sourceRoomId": "!admin-dm:matrix.local",
    "assignedTo": "@worker-a:matrix.local",
    "roomId": "!task-room:matrix.local",
    "spec": "# Task\n\nWrite one concise readiness note.",
    "replyRoute": {
      "channel": "matrix",
      "targetUser": "@admin:matrix.local",
      "targetSession": "!admin-dm:matrix.local"
    }
  }
}

This writes:

shared/projects/{projectId}/meta.json
shared/projects/{projectId}/plan.md
shared/tasks/{taskId}/meta.json
shared/tasks/{taskId}/spec.md

It sets mode: quick, plan_type: dag, and the single task status to assigned. It does not send the Matrix or external-channel assignment message; send that message only after the tool returns ok: true.

Plan DAG

Use DAG when the work is finite and dependencies are known enough to plan now.

Call plan_dag with the complete graph you want to keep:

{
  "action": "plan_dag",
  "payload": {
    "projectId": "demo-project-001",
    "tasks": [
      {
        "taskId": "demo-project-001-01",
        "title": "Implement the worker-owned part",
        "assignedTo": "@worker-a:matrix.local",
        "dependsOn": []
      }
    ]
  }
}

For assignedTo, use the Worker Matrix ID or the stable runtime/member name from TEAMS.md. Do not invent a Worker name.

plan_dag returns readyNodes. Delegate only ready nodes.

Ready Nodes

Use ready_nodes when you need the next pending or assigned DAG nodes whose dependencies are completed:

{
  "action": "ready_nodes",
  "payload": {
    "projectId": "demo-project-001"
  }
}

Only nodes with dependencies marked completed unblock downstream work.

Plan Loop

Use Loop when teamharness-team-coordination decided the work should repeat until a stop condition, quality gate, evidence threshold, or maximum iteration count.

Call plan_loop with the complete current-iteration plan you want to keep:

{
  "action": "plan_loop",
  "payload": {
    "projectId": "demo-project-001",
    "goal": "Improve the result until tests pass",
    "stopCondition": "All target tests pass or maxIterations is reached",
    "iterationTemplate": "Inspect result, choose one bounded fix, run tests.",
    "maxIterations": 3,
    "currentIteration": 1,
    "tasks": [
      {
        "taskId": "demo-project-001-i001-01",
        "title": "Run iteration 1",
        "assignedTo": "@worker-a:matrix.local",
        "dependsOn": []
      }
    ]
  }
}

Required Loop inputs:

• goal
• stopCondition
• iterationTemplate
• maxIterations

Use ready_loop_nodes to find pending nodes in the current iteration whose dependencies are completed:

{
  "action": "ready_loop_nodes",
  "payload": {
    "projectId": "demo-project-001"
  }
}

After evaluating an iteration, use record_loop_iteration:

{
  "action": "record_loop_iteration",
  "payload": {
    "projectId": "demo-project-001",
    "iteration": 1,
    "decision": "continue",
    "summary": "One target still fails.",
    "nextAction": "Plan the next fix pass."
  }
}

Allowed decisions are continue, replan, ask_user, stop_success, and stop_blocked.

Do not pre-expand repeated Loop rounds into a large DAG. Plan the current iteration, evaluate it, record the iteration decision, then decide whether to continue, replan, ask the requester, stop successfully, or stop blocked.

Resolve Project Context

When a Worker completion or blocker wakes the Leader in a fresh session, do not guess the project from the current room. First resolve the context from the task id:

{
  "action": "resolve_project",
  "payload": {
    "taskId": "demo-project-001-01"
  }
}

resolve_project returns the ProjectMeta, TaskMeta, replyRoute, plan type, and ready nodes that the Leader needs to resume normal project flow.

Accepting Worker Results

A Worker SUCCESS or SUCCESS_WITH_NOTES result is only a candidate result. After teamharness-task-delegation checks the task and returns effective: true, decide whether to accept the result.

To accept a result, call accept_task_result:

{
  "action": "accept_task_result",
  "payload": {
    "projectId": "demo-project-001",
    "taskId": "demo-project-001-01",
    "resultStatus": "SUCCESS",
    "summary": "Completed the assigned work."
  }
}

accept_task_result updates the DAG or Loop node and records requester_report.pending in ProjectMeta. Keep unresolved nodes in their current state.

Accepting a completed result does not publish the project artifact by default. Write or update shared/projects/{project-id}/result.md as the Leader when a project-level report file is needed. After the requester report message is sent to a Matrix requester room, publish shared/projects/{project-id}/result.md with artifact publish_file and set parentEventId to the report message id. Use publishArtifacts: true only when you intentionally want an immediate project artifact before the requester report.

Then call ready_nodes and delegate any newly ready downstream node with teamharness-task-delegation.

After the project state changes, close the loop with requester visibility:

1. Read shared/projects/{project-id}/meta.json and plan.md.
2. Build the requester-facing content with the Project Status Reports template below.
3. Use teamharness-communication ## Requester Report Delivery Protocol to deliver the report to the requester recorded on the project.
4. If the requester report was sent to a Matrix room and shared/projects/{project-id}/result.md exists, call artifact publish_file for that file with parentEventId set to the report message id.
5. If the requester report was sent to DingTalk, Feishu, WeChat, or another non-Matrix channel, do not claim that a file was attached or published in that channel. In the report text, list the important shared/... artifact paths and say they are available from the shared workspace or platform object-storage view.
6. After successful delivery, call mark_requester_report_sent.

Task room coordination, Worker completion messages, downstream assignment messages, and tool-call summaries do not count as the requester report. You may batch several accepted task results and downstream delegations into one requester report, but do not omit the report when accepted project state changed.

Project Status Reports

Build status report content here because this skill owns project execution state. Use teamharness-communication only for destination selection, message tool payloads, Matrix message formatting, and same-room versus cross-room delivery.

Before writing a requester report:

1. Read shared/projects/{project-id}/meta.json and plan.md.
2. Identify the plan type from meta.json or plan.md.
3. For DAG, report dependency progress and the next ready nodes.
4. For Loop, report current iteration progress, the latest decision, and the next iteration path.
5. Write the report in the requester's language, then use teamharness-communication to deliver it to the requester recorded on the project.

Use stable state markers and localize the visible labels:

Keep the report envelope consistent across DAG and Loop:

---

## <localized project status report heading>

**<localized project name label>**: <name>
**<localized project ID label>**: <project-id>
**<localized execution mode label>**: <DAG or Loop>
**<localized project status label>**: <marker + localized state label>
**<localized current focus label>**: <DAG wave/current node, or Loop iteration n / max and topic>

**<localized summary label>**: <1-3 sentences about what changed and what happens next>

**<localized task status label>**:
| <localized task ID label> | <localized task title label> | <localized owner label> | <localized status label> | <localized context label> |
|---|---|---|---|---|
| <task-id> | <title> | <worker> | <marker + localized state label> | <dependencies, iteration role, result note, or -> |

**<localized execution progress label>**:
```text
<DAG dependency flow or Loop iteration line; choose the matching shape below>
```

**<localized deliverables label>**:
- `<path>` - <what it contains>

For Matrix requester reports, this section may say the report file or artifact
was published to the requester room only after `artifact publish_file` succeeds.
For DingTalk, Feishu, WeChat, or other non-Matrix requester reports, say the
files are available from the shared workspace or platform object-storage view;
do not say "attached", "uploaded to this chat", "click the file card", or
"view the file here".

**<localized next steps label>**:
1. <next DAG transition, next Loop decision, or requester action>

**<localized notes label>**: <blocker, risk, or decision needed; omit section if none>

In requester-facing reports, owner or executor cells are descriptive text. Use plain Worker display names or role names such as workeraa, workerbb, or WorkerAA. Do not prefix them with @, do not use full Matrix user ids, and do not create Matrix mention links unless the report is intentionally asking that member to respond or take action.

Use this execution progress shape for DAG reports:

<task-id> [done] -> <task-id> [active] -> <task-id> [pending]
                                  ^
<task-id> [done] -----------------|

Use the DAG progress section to show the dependency path that changed, newly unblocked nodes, or the next ready wave. If the graph is large, show only the relevant changed path and summarize the rest in the task table.

Use this execution progress shape for Loop reports:

Iteration 1 [done] -> Iteration 2 [active] -> Iteration 3 [pending] ... Max <n>
                       Current: <current iteration topic>
                       Decision: <continue, replan, ask_user, stop_success, stop_blocked, or pending evaluation>

Use the Loop progress section to show current iteration number, maximum iterations, current iteration topic, and the latest Leader decision. Do not present future Loop rounds as if they were pre-planned DAG tasks. Show only the current iteration's task statuses in the task table unless prior iteration context is necessary.

For intermediate updates, include the Project header, summary, task status table, and next steps. Omit the deliverables section unless new deliverables are available, and omit the execution progress section only when neither DAG flow nor Loop iteration state changed.

After the requester report is sent, clear the pending flag:

{
  "action": "mark_requester_report_sent",
  "payload": {
    "projectId": "demo-project-001"
  }
}

Post-Action Notification

State-mutating projectflow and taskflow operations return a notificationNeeded field when they succeed. This field is a hint — the tool does not send any message automatically. The Leader must act on it.

When notificationNeeded is present in the tool result:

1. Check notificationNeeded.targetRoom. If it matches the current session room, a direct reply in the current session is sufficient — no cross-room message is needed.
2. If targetRoom is a different room, use the message tool to send a brief status update to that room. Use m.notice-style concise format: [ProjectFlow] {event}: {summary}.
3. If notificationNeeded.replyRoute is present and the event is accept_task_result or complete_project, this is the requester report trigger — follow the Requester Report Delivery Protocol in teamharness-communication.
4. Do not send a notification if the tool returned ok: false.
5. Do not send duplicate notifications for the same event within a single Leader turn — one notification per state change is sufficient.

The notificationNeeded field contains:

{
  "event": "create_project",
  "projectId": "demo-project-001",
  "summary": "create_project: Demo Project",
  "targetRoom": "!task-room:matrix.local",
  "replyRoute": { "channel": "matrix", "targetSession": "..." }
}

targetRoom and replyRoute may be absent when no room context is available (for example, a bare create_project before any task room exists). In that case, skip the notification — the assignment message or requester report will carry the project context later.

Current Boundary

TeamHarness v0.1 supports project creation, quick single-task project creation, project context resolution, DAG planning, DAG ready-node resolution, Loop planning, Loop ready-node resolution, Loop iteration recording, explicit result acceptance, requester report clearing, pause_project, resume_project, and complete_project. DAG and Loop task plans reject duplicate task ids, unknown dependencies, and dependency cycles. Do not call unsupported projectflow actions.