{"id":51095616,"url":"https://github.com/vector233/ai-collaboration-workflow-template","last_synced_at":"2026-06-24T06:02:15.175Z","repository":{"id":361813771,"uuid":"1239896212","full_name":"vector233/ai-collaboration-workflow-template","owner":"vector233","description":"A Zettelkasten-style, Obsidian-compatible AI collaboration workflow template for long-running software projects.","archived":false,"fork":false,"pushed_at":"2026-06-18T09:42:13.000Z","size":191,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-18T11:26:27.931Z","etag":null,"topics":["ai-agents","ai-coding","claude-code","codex","documentation-template","markdown","obsidian","project-management","software-engineering","zettelkasten"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vector233.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-15T14:55:45.000Z","updated_at":"2026-06-18T09:42:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vector233/ai-collaboration-workflow-template","commit_stats":null,"previous_names":["vector233/ai-collaboration-workflow-template"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/vector233/ai-collaboration-workflow-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vector233%2Fai-collaboration-workflow-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vector233%2Fai-collaboration-workflow-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vector233%2Fai-collaboration-workflow-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vector233%2Fai-collaboration-workflow-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vector233","download_url":"https://codeload.github.com/vector233/ai-collaboration-workflow-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vector233%2Fai-collaboration-workflow-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34719307,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-24T02:00:07.484Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ai-coding","claude-code","codex","documentation-template","markdown","obsidian","project-management","software-engineering","zettelkasten"],"created_at":"2026-06-24T06:02:13.954Z","updated_at":"2026-06-24T06:02:15.068Z","avatar_url":"https://github.com/vector233.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AI Collaboration Workflow Template\n\nA Zettelkasten-style, Obsidian-compatible documentation template for long-running software projects built with AI coding agents.\n\nThis repository packages a practical AI collaboration workflow. It gives agents a durable project memory, explicit requirement and design gates, evidence-based review handoffs, and a place to write back lessons after each slice of work.\n\n## Quick Start\n\n1. Install the companion Skill and ask:\n\n   ```text\n   Use $ai-collaboration-workflow to initialize this repository.\n   ```\n\n   Or copy the canonical payload into an existing repository:\n\n   ```bash\n   cp -R /path/to/ai-collaboration-workflow-template/template/. /path/to/your-project/\n   ```\n\n2. If you copied the payload manually, ask your AI coding assistant:\n\n   ```text\n   Initialize this knowledge base by following INIT.md.\n   ```\n\n3. Start non-trivial work with the workflow below.\n\n```text\nTask\n  -\u003e REQ       define scope, non-goals, and acceptance criteria\n  -\u003e [TECH]    add a standalone technical design when risk or uncertainty requires it\n  -\u003e [PLAN]    add a standalone execution plan when coordination requires it\n  -\u003e Build     implement one bounded slice and run meaningful validation\n  -\u003e REVIEW    hand off evidence, feedback, and risk\n  -\u003e Writeback update durable knowledge and close the loop\n```\n\n| Stage | Artifact | Purpose |\n|---|---|---|\n| Requirement | `REQ-*` | Define what changes and how it will be accepted |\n| Technical design, optional | `TECH-*` | Resolve architecture, contract, risk, and operational decisions |\n| Implementation plan, optional | `PLAN-*` | Make dependencies, ownership, sequence, and checkpoints explicit |\n| Implementation and validation | Code/docs slice plus evidence | Keep the change bounded and verify the changed boundary |\n| Review | `REVIEW-*` | Preserve feedback, evidence, and risk |\n| Writeback | Architecture/gotchas/runbooks | Keep future agents from rediscovering context |\n\n## What It Solves\n\nAI coding agents are strong at local implementation but weak at long-lived project continuity unless the project gives them structure. This template turns project documentation into a lightweight operating workflow:\n\n- **Context pack**: agents read the smallest necessary context instead of re-discovering the whole repo.\n- **Requirement workflow**: every non-trivial change has scope, acceptance criteria, and known non-goals.\n- **Adaptive design and planning**: standalone TECH and PLAN documents are used when risk or coordination justifies them; bounded bugs can keep the necessary reasoning inside the REQ.\n- **Review handoff**: review feedback is treated as a hypothesis that needs evidence and independent verification.\n- **Validation discipline**: build, test, browser, integration, and realistic-environment checks are recorded where future agents can find them.\n- **Memory writeback**: architecture changes, test procedures, and gotchas are written back into the knowledge base.\n\nThe default template is intentionally plain: no specialized process jargon, no heavy role system, and no requirement to run multiple agents.\n\n## Zettelkasten Inspiration\n\nThis template is inspired by the Zettelkasten note-taking method: small notes, explicit links, and knowledge that grows through connections instead of one large document. In this project, that idea is adapted for AI coding agents: requirements, technical designs, review handoffs, architecture notes, validation runbooks, and gotchas are separate notes that link to each other.\n\nThe goal is practical retrieval. A future agent should be able to start from a task, follow links to the minimum context, do the work, and write back what changed.\n\n## Obsidian And Markdown Compatibility\n\nThe knowledge base is designed to work well as an Obsidian vault, but it stays close to plain Markdown where that helps GitHub readability.\n\n| Use case | Preferred syntax | Notes |\n|---|---|---|\n| Link between notes in `zettelkasten/` | `[[00-governance/ai-workflow]]` | Obsidian-compatible wiki link; compact and good for graph navigation |\n| External links | `[label](https://example.com)` | Standard Markdown; works in Obsidian and GitHub |\n| Images or assets that should render on GitHub | `![alt](assets/example.png)` | Standard Markdown image syntax |\n| Obsidian-only embeds | `![[example.png]]` | Good inside Obsidian, but not rendered by GitHub Markdown |\n\nObsidian supports both wiki links and Markdown links for internal notes. This template uses wiki links for project-note navigation because the Zettelkasten graph is the core workflow. Use standard Markdown links and images when the content should render cleanly outside Obsidian.\n\n## Language\n\nThe template is English-first. Keeping the canonical version in one language reduces drift and makes the project easier to reuse globally. Translations can be added later as guides under `docs/zh-CN/` without duplicating the full template.\n\nChinese guide: [docs/zh-CN/README.md](docs/zh-CN/README.md).\n\n## Structure\n\n```text\n.\n├── template/                  # Canonical downstream payload\n│   ├── AGENTS.md\n│   ├── CLAUDE.md\n│   ├── INIT.md\n│   └── zettelkasten/\n├── skills/\n│   └── ai-collaboration-workflow/\n├── scripts/\n│   └── validate_distribution.py\n├── docs/                      # Maintainer and publishing documentation\n└── examples/                  # Fictional initialized-project walkthroughs\n```\n\nOnly `template/` is downstream project content. The repository intentionally has no second root knowledge base, which keeps product files distinct from maintainer documentation.\n\n## Install The Template Payload\n\n1. Use the Skill bootstrap, or copy everything under `template/` into the target repository. This includes `INIT.md`.\n2. In your AI coding tool, say:\n\n   ```text\n   Initialize this knowledge base by following INIT.md.\n   ```\n\n3. Answer the initialization questions.\n4. Let the agent replace placeholders, merge project-specific `AGENTS.md` rules, prune single-repo or umbrella-only sections, create the first notes, and remove `INIT.md`. Commit only when requested or required by repository policy.\n\nDo not treat the full repository root as the install payload. GitHub's template-repository feature copies maintenance files as well, so the supported clean installation surfaces are the Skill and `template/`.\n\n## Daily Workflow In An Initialized Project\n\nFor non-trivial work, agents should follow this loop:\n\n1. Read `AGENTS.md`, `zettelkasten/AI.md`, and `zettelkasten/00-governance/ai-workflow.md`.\n2. Find or create the relevant requirement under `zettelkasten/06-requirements/`.\n3. In the REQ, decide whether standalone TECH and PLAN documents are required.\n4. Approve required TECH/PLAN artifacts, or complete inline readiness and slices in the REQ.\n5. Implement only the current slice and run the smallest meaningful validation.\n6. Create or update a review handoff under `zettelkasten/07-review/`.\n7. Handle reviewer feedback with evidence, then write durable lessons back to `00-governance/gotchas.md`, `02-architecture/`, or `05-reference/`.\n\nSee `examples/example-saas/` for a fictional end-to-end walkthrough.\n\nTo evaluate whether a fresh agent can resume from repository state alone, use [docs/fresh-agent-resume-evaluation.md](docs/fresh-agent-resume-evaluation.md).\n\n## Cross-Agent Compatibility\n\nThe workflow is vendor-neutral; tool-specific files are thin adapters:\n\n| Agent | Project instruction entry | Shared workflow state |\n|---|---|---|\n| Codex | `AGENTS.md` | `zettelkasten/` |\n| Claude Code | `CLAUDE.md` imports `AGENTS.md` | `zettelkasten/` |\n| Other repository-aware agents | explicitly read `AGENTS.md` | `zettelkasten/` |\n\nRequired project state must not live only in a chat transcript, Codex memory, Claude auto memory, or another agent's private state. A different agent must be able to resume from the active REQ, any controlling TECH or PLAN, open REVIEW, validation evidence, worktree state, risks, and next allowed action.\n\nThe companion Skill follows the open Agent Skills format used by both Codex and Claude Code, but the core workflow does not depend on the Skill being installed after initialization.\n\n## Optional External Process Skills\n\nThe initialized template does not require Superpowers or any other process plugin. Codex, Claude Code, and other repository-aware agents can use `REQ -\u003e [TECH] -\u003e [PLAN] -\u003e implementation and validation -\u003e REVIEW -\u003e writeback` with only the files in the target repository.\n\nIf Superpowers is installed, repository instructions map its brainstorming, planning, TDD, debugging, and review methods into the selected REQ, TECH, PLAN, REVIEW, gotcha, and runbook documents. It must not create a parallel `docs/superpowers/` source of truth.\n\nThis is compatibility only:\n\n- no external plugin is installed by the template;\n- no external command is required;\n- standalone TECH and PLAN artifacts remain optional unless the REQ marks them required;\n- removing or disabling the external plugin does not change the repository workflow.\n\n## Companion Skill\n\nThis repository includes an optional Agent Skills-compatible skill:\n\n```text\nskills/ai-collaboration-workflow/\n```\n\nUse it when you want an AI agent to apply the template consistently: initialize a project, create REQ/TECH/PLAN/REVIEW documents when appropriate, check implementation readiness, record validation, handle evidence-based review feedback, and write lessons back to the knowledge base.\n\nThe skill is a companion to the template. If you invoke it in a project that does not yet contain `AGENTS.md`, `CLAUDE.md`, and `zettelkasten/`, it can safely bootstrap the template before continuing. Its bootstrap script previews changes, copies only missing files, skips identical files, and leaves differing existing files untouched for explicit merging.\n\nInstall with skills.sh:\n\n```bash\nnpx skills add vector233/ai-collaboration-workflow-template \\\n  --skill ai-collaboration-workflow \\\n  -a claude-code \\\n  -g\n```\n\n### Install For Claude Code\n\nPersonal install, available across all Claude Code projects:\n\n```bash\nmkdir -p ~/.claude/skills\ncp -R skills/ai-collaboration-workflow ~/.claude/skills/\n```\n\nProject install, committed to one repository:\n\n```bash\nmkdir -p .claude/skills\ncp -R skills/ai-collaboration-workflow .claude/skills/\ngit add .claude/skills/ai-collaboration-workflow\n```\n\nThen start Claude Code in the project and invoke:\n\n```text\n/ai-collaboration-workflow create a requirement for \u003ctask\u003e\n```\n\nClaude may also load the skill automatically when your request matches the skill description.\n\n### Install For Codex\n\n```bash\nmkdir -p ~/.codex/skills\ncp -R skills/ai-collaboration-workflow ~/.codex/skills/\n```\n\nThen invoke:\n\n```text\nUse $ai-collaboration-workflow to initialize this repository.\n```\n\nFor an initialized project:\n\n```text\nUse $ai-collaboration-workflow to choose the delivery path and create the required workflow artifacts.\n```\n\nThe default bootstrap source is this canonical Git repository and automatically selects its `template/` directory. For offline use, pass either the repository checkout or `template/` directly with `--source`.\n\n## Distribution Validation\n\nRun:\n\n```bash\npython3 scripts/validate_distribution.py\n```\n\nThe smoke test checks payload isolation, state-directory presence, bootstrap dry-run and installation, sample initialization, wiki links, a bounded REQ-only bug path, and a full REQ/TECH/PLAN/REVIEW path.\n\n## Naming Rules\n\n- Requirements: `REQ-YYYYMMDDHHMMSS-short-name.md`\n- Technical designs: `TECH-YYYYMMDDHHMMSS-short-name.md`\n- Implementation plans: `PLAN-YYYYMMDDHHMMSS-short-name.md`\n- Review handoffs: `REVIEW-YYYYMMDDHHMMSS-short-name.md`\n\n## What To Customize\n\nStart with these files after initialization:\n\n- `AGENTS.md`: repo-specific AI rules, build commands, test discipline, branch policy.\n- `zettelkasten/00-governance/project-overview.md`: project purpose, stack, constraints.\n- `zettelkasten/01-overview/quick-reference.md`: commands, URLs, ports, test accounts, runbooks.\n- `zettelkasten/02-architecture/current-architecture-flow.md`: current system flow.\n- `zettelkasten/05-reference/e2e-test.md`: project-specific validation commands.\n\n## License\n\nMIT. Use it, fork it, and adapt it to your own AI engineering workflow.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvector233%2Fai-collaboration-workflow-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvector233%2Fai-collaboration-workflow-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvector233%2Fai-collaboration-workflow-template/lists"}