# Doc Business Rules

> Agach business rules: blocking workflow, won't-do workflow, GetNextTask logic, resolution auto-append, priority system, comment system, features

- Skill: `jlugagne/doc-business-rules` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jlugagne/doc-business-rules`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jlugagne/doc-business-rules/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: JLugagne (https://skillmd.com/u/jlugagne)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jlugagne/doc-business-rules

---


# Agach Business Rules

## Column Structure (5 Columns)
```
1. backlog       (position -1) - Backlog, created on-demand via EnsureBacklog
2. todo          (position 0)  - Tasks to be done
3. in_progress   (position 1)  - Tasks being worked on
4. done          (position 2)  - Completed tasks
5. blocked       (position 3)  - Tasks requiring human intervention
```

Default columns (todo, in_progress, done, blocked) are created automatically when a project is created.
Backlog column is created on-demand via `EnsureBacklog()`.

## Task Fields

**Required at creation**: `Title` and `Summary`
**Resolution**: Filled when agent stops work or human moves task back to todo

**Key State Flags:**
- `IsBlocked` = true when task is IN the "blocked" column
- `WontDoRequested` = true when task is IN "blocked" column awaiting human decision

**Token Tracking**: `InputTokens`, `OutputTokens`, `CacheReadTokens`, `CacheWriteTokens`, `Model`
**Cold Start Tracking**: `ColdStartInputTokens`, `ColdStartOutputTokens`, etc. (SET semantics, not accumulated)
**Duration Tracking**: `StartedAt`, `DurationSeconds`, `HumanEstimateSeconds`
**Session**: `SessionID` for Claude Code session resuming

## Features
- Features are project-scoped groupings of tasks
- Status: draft → ready → in_progress → done → blocked
- Tasks have optional `FeatureID` linking them to a feature
- Sub-projects were migrated to features (002_features.sql)

## Blocking Workflow
- Agent calls `block_task` → task **moves to "blocked" column**, sets `is_blocked=true`
- Task is visible in Blocked column (not flagged in Todo)
- Only humans can unblock via web UI → moves back to "todo", sets `is_blocked=false`
- Blocked tasks invisible to `get_next_task`

## Won't-Do Workflow
- Agent calls `request_wont_do` → task **moves to "blocked" column** with `wont_do_requested=true`
- Human sees task in Blocked column with "Won't Do Requested" badge
- Human approves → **task moved to "done" column** with `wont_do_requested=true` kept (displays as "won't do")
- Human rejects → adds comment, moves back to "todo", clears `wont_do_requested`
- Won't-do-requested tasks in "blocked" column invisible to `get_next_task`
- Won't-do tasks in "done" column count as resolved dependencies

## GetNextTask Rules
- Returns highest-priority task in "todo" column (not backlog) with all dependencies resolved
- A dependency is "resolved" if its task is in the "done" column (including won't-do approved)
- Filters: `is_blocked=false`, `wont_do_requested=false`
- Role filtering: empty role → unassigned tasks only; specified role → matching or unassigned
- Sorts by `priority_score DESC`, `created_at ASC`
- Optional `featureID` parameter to scope search to a specific feature

## Resolution Auto-Append
When human moves task from "in_progress" to "todo":
```go
if resolution == "" {
    resolution = "[Moved back to Todo by human on {date} - task was not completed]"
} else {
    resolution += "\n\n[Moved back to Todo by human on {date} - task was not completed]"
}
```

## Priority System
Simple 4-level system only:
- `critical` → 400
- `high` → 300
- `medium` → 200
- `low` → 100

**NO dynamic boosting, NO urgency calculations, NO dependency boosting**

## Comment System
- `author_type` field: "agent" or "human"
- No comment types/categories
- Auto-comments for system actions (blocking, won't-do, etc.)

## Chat Sessions
- Feature-scoped chat sessions that spawn Claude CLI processes on the daemon
- State: active → ended / timeout
- 30-minute idle TTL with 25-minute warning
- Token usage tracked per session (input/output/cache_read/cache_write)
- JSONL capture of full conversation, uploaded to server on session end

## Agent/Role System
- Global agents (roles) with slugs, icons, colors, tech stacks, prompt templates
- Project-scoped agent assignment via `project_agents`
- Specialized agents: variants under a parent agent with specific skill sets
- Skills: global definitions assignable to agents and specialized agents
- Agent cloning: duplicate an existing agent with new slug/name

## Notification Triggers
| Trigger                        | Scope     | Severity  |
|--------------------------------|-----------|-----------|
| Feature status → `done`        | project   | `success` |
| Feature status → `blocked`     | project   | `warning` |
| Task blocked                   | project   | `warning` |
| Task won't-do requested        | project   | `warning` |
| All feature tasks completed    | project   | `success` |
| Agent build failure            | agent     | `error`   |
| System maintenance             | global    | `info`    |