name: human-ai-collaboration-protocol description: Structured workspace protocol for human-AI collaboration. Governs milestones, task lifecycle, context snapshots, and workspace consistency using docs/TEMPLATE_GUIDE.md as source of truth. Use when workspace follows template-style layout with docs/state/logs/prompts directories.

Workspace Template Steward (Docs/State/Logs/Prompts)

When to use

Use this skill when a workspace follows the template-style collaboration layout, especially when docs/TEMPLATE_GUIDE.md exists.

Prefer this skill when the workspace shows the new governance architecture:

• docs/milestones.md uses task session as the primary stage task view
• state/tasks/{active,done,packaged} exists
• state/control_tower.md is optional coordination board (not mandatory detailed backlog)
• docs/specs/INDEX.md exists and schemas are directory-based

Core rules

• Treat docs/TEMPLATE_GUIDE.md as source of truth.
• docs/milestones.md task session is primary for stage task progression.
• state/control_tower.md is optional; use it only for cross-milestone coordination/blockers.
• Do not force fixed project-global filenames in docs/; create project-global docs on demand.
• Do not reintroduce deprecated/legacy structures.

Examples:

• If state/tasks/ exists, do not create new state/task_*.md at root.
• If a log file is marked deprecated, do not append to it.
• If a domain is marked closed, do not regenerate legacy artifacts unless user asks.

Workflow

1) Identify workspace root

• Default to current working directory.
• If user provided another root, confirm before writing.

2) Read minimal context at task start

Priority order:

1. docs/TEMPLATE_GUIDE.md
2. state/context.md
3. docs/milestones.md
4. related state/tasks/active/task_*.md
5. docs/workspace_objects.md (if task involves object definitions or role split)
6. docs/specs/INDEX.md + required docs/specs/schemas/*.schema.json (if task involves schema)
7. relevant state/requirements/*.md (task-scoped)
8. state/control_tower.md (only if exists and needed for cross-milestone coordination)

3) Initialize structure (idempotent, no regression)

Create missing files only if guide expects them.

Typical baseline in new architecture:

• docs/TEMPLATE_GUIDE.md
• docs/milestones.md
• docs/workspace_objects.md (if used by guide)
• docs/specs/INDEX.md
• state/context.md
• state/tasks/active/
• state/tasks/done/
• state/tasks/packaged/
• logs/work_log_user.md
• logs/changes_log_[milestone_name].md (or guide-defined active log)
• prompts/INDEX.md

Optional (create only when guide/task needs):

• state/control_tower.md
• state/domains/
• project-global docs under docs/ (named by task needs, not fixed)

4) Task lifecycle management

• Create new execution tasks in state/tasks/active/.
• Keep reusable task packs in state/tasks/packaged/.
• Move completed tasks to state/tasks/done/.
• Keep long-term archives in state/history/tasks/.
• Update task progression primarily in docs/milestones.md task session.
• If control tower exists, only register cross-milestone coordination items there.

5) On task completion

• update docs/milestones.md task session/status for related milestone
• append concise change notes to the correct active log file(s)
• update state/context.md minimal snapshot
• if task is done, move its file to state/tasks/done/
• if prompt files changed, update prompts/INDEX.md
• update state/control_tower.md only when coordination/blocker state changed

6) Log routing

Always follow the guide's active log mapping.

• append only to active logs
• do not append to logs marked deprecated/pointer-only

7) Domain artifacts (state/domains/)

If the workspace uses state/domains/:

• treat it as domain-based artifact storage (state/domains/<domain_name>/)
• do not assume one domain per milestone
• keep naming and routing consistent with docs/TEMPLATE_GUIDE.md

8) Optional attachments handling

If attachments_manifest.json exists, treat it as source of truth and keep it synced with attachments/ and new_attachments/ according to project rules.

Safety guardrails

• Never overwrite existing files unless user asked.
• Never delete attachments by default.
• For major directory cleanup/migration, require explicit user confirmation.
• Avoid rewriting template rules with project-private content unless user explicitly requests it.

Fast path

Use the bundled init script only when it matches the current guide:

• python3 <SKILL_DIR>/scripts/init_workspace.py --root <workspace-root> --update-index

Where <SKILL_DIR> is the directory containing this SKILL.md file.

If script behavior conflicts with current guide conventions, follow the guide manually and avoid destructive automation.