Status	Last updated	Parent	Read before this
complete	2026-04-30	none	Product - Vision

Architecture Overview

Current state

devwork-skills is a set of Claude Code skills that drive a feature end-to-end through a fixed pipeline, with the orchestrator (a human today, an agent tomorrow) intervening only at decision points. The architecture has four layers, each isolated from the layers below it.

The orchestrator consumes Contract - Phase Outcome and resolves pending decisions. It's pluggable: today an interactive Claude Code session driven by a human PM; tomorrow potentially a dashboard, a chat bot, or another agent. Skills don't know who or what is orchestrating them. See Role - The Orchestrator.

Main SDLC skills are forge-agnostic and do the work. They produce deliverables and emit a Phase Outcome. They call abstract operations (create_issue, post_phase_outcome, set_status, read_wiki_page) without knowing which forge implements them. The pipeline of skills is documented in Design - Skill Pipeline. The agents and Agent Teams that skills spawn are described in Role - Coding Harness Agents.

The forge contract is the neutral specification both sides agree to. It's a document in _shared/, not executable code. Main skills read it to know what they may call; adapters read it to know what they must implement. The contract grows when the SDLC needs new operations, not speculatively. See Contract - Forge Adapter.

Forge adapter skills implement the contract for a specific platform: /tea-cli for Forgejo, /glab-cli for GitLab, /gh-cli for GitHub, /local-fs for projects with no remote forge. Adapters own all the platform-specific decisions: CLI invocation, label conventions, link syntax, wiki rendering, polyfill choices. Each adapter declares its capability manifest in its own SKILL.md — the adapter is the source of truth for what it supports.

The two durable substrates the system writes to are the issue tracker (Design - Issues As Durable Record) and the wiki (Design - Wiki Layer). Issues hold transactional work-in-progress; the wiki holds stable system knowledge. Local artifacts and the sync model are covered in Design - Artifacts.

Rationale

The four-layer split exists because forges differ in three dimensions that all leak if not isolated: capability surface (GitLab Premium projects vs Forgejo's labels-only), data model (folder-structured wikis vs flat-plus-sidebar), and CLI shape (tea, glab, gh). Without an explicit contract, every main skill ends up with a if forge == "gitlab" branch and the system can't move to a new forge without rewriting every skill.

The orchestrator was lifted out of the skills for the same reason. When approval gates and decision-handling lived inside skills, "who decides" was hardcoded as "interactive Claude Code session." Externalising decisions through Phase Outcomes makes the orchestrator pluggable — the skill's job is to produce decisions, not to resolve them. This is what enables a future dashboard, a future agentic orchestrator, or an external PM workflow to drive the pipeline without changes to skill code.

The local-fs adapter is architecturally identical to remote adapters. This isn't a curiosity — it's load-bearing. The contract-level skills can be developed and tested against local-fs without a real forge, and projects that don't want or have a remote can run the same pipeline.

The system is designed for a single feature traveling through the pipeline as one issue, not for code-level debugging — git history and PRs cover that. The issue is the long-term answer to "why does the system do X."

Open questions

• The documentation agent is described in Role - The Documentation Agent but isn't yet implemented. Several open questions about its canonical input, approval gate, and initial taxonomy seeding remain — see that page.