Zazz Methodology & Skills

Zazz is an operating model for the agentic software delivery lifecycle. It helps teams use agents to move faster while keeping product direction, engineering quality, review discipline, and merge authority in human hands.

This repository is the canonical source for the Zazz methodology and shared skills. Downstream repos can vendor or sync these docs and skills, but methodology changes should land here first.

Executive Overview

AI agents can produce code quickly. The hard part is making sure the team is building the right thing, the implementation is reviewable, the evidence is credible, and the knowledge survives after merge. Zazz provides the structure for that.

Zazz gives executives and engineering teams:

• Faster delivery with control: agents can implement and verify bounded work, while humans keep scope, product signoff, review, approval, and merge authority.
• Clearer product intent: project.md, proposals, architecture docs, feature requirements, and project milestones preserve why the work matters and when stakeholders should expect outcomes.
• Executable delivery contracts: deliverable specifications turn intent into scoped implementation work with acceptance criteria, test strategies, standards, and halt conditions.
• Spec-driven implementation: approved specifications stay current through implementation, Deliverable Owner steering, QA, and PR review by updating the spec body in place and recording contract changes.
• Ongoing standards conformance: localized, evidence-backed maintenance PRs keep legacy and existing code aligned with adopted standards instead of letting drift accumulate.
• Cleaner parallel execution: isolated worktrees keep active agent work separate, recoverable, and easier to coordinate across teams or branches.
• Stronger review signal: qa-testing verifies behavior and evidence, pr-builder packages the pull request, and pr-review runs automated self-review before human review and merge.
• Durable organizational knowledge: shipped work updates product, architecture, and standards docs so decisions do not disappear into chats, tickets, or PR comments.

The methodology is intentionally Git-native. Durable docs, code, review evidence, automated review, human approval, and merge all move through normal branch and PR workflows. The shared skills in .agents/skills/ operationalize the workflow so teams can apply it consistently across projects and agent runtimes.

Quick Links

• Methodology overview
• Methodology sections
• Standards baseline
• Standards index
• AGENTS.md example template
• Worktree setup guide
• Agent execution discipline
• Worktrunk cheat sheet
• GH-stack guide
• Human-in-the-loop PR review strategy
• Code review graph guidance
• Reference implementation: zazz-board

Workflow

project.md
  -> architecture.md
  -> proposals/
  -> features/ for capability context
  -> project milestones / roadmap for timeline planning
  -> specifications/
  -> spec-driven development
  -> deterministic quality gates
  -> standards conformance maintenance
  -> code generation
  -> testing and validation
  -> PR packaging and automated review
  -> human review and merge

Read zazz-methodology.md for the entry point, then use the focused methodology sections for the part of the workflow you are working on.

Document Model

The document framework is project-first. Each repo declares its docs root in AGENTS.md, commonly docs/ or .zazz/. Repos that resolve the docs root from an environment variable should use ZAZZ_DOCS_ROOT, and its value must be a repo-relative path such as docs, .zazz, or packages/platform-docs.

<DOCS_ROOT>/
├── project.md
├── standards/
├── proposals/
├── features/
├── architecture/
├── specifications/
└── ephemeral/

The specifications/ directory is the normal local working directory for spec-builder files. The repo's AGENTS.md declares whether it is tracked, ignored, mirrored, or promoted to another durable system. Other durable locations, such as roadmap, project plans, project milestones, or wiki/knowledge-base pages, are also declared by the repo's operating model.

Each document type exists to solve a different coordination problem:

• project.md provides top-level durable orientation for the software project.
• standards/ defines how the software should be built.
• proposals/ provides a durable place to work through uncertainty before committing to a direction.
• features/ contains long-lived feature requirements documents for capability intent and feature roadmap increments.
• Project milestones are project-owned timeline containers that communicate when work is expected to land; a single project milestone can contain deliverables from multiple features.
• architecture/ contains project-level or feature-level technical design.
• specifications/ contains deliverable specifications authored by spec-builder and executed by Contributor Agents inside the worktree; the repo decides whether they are committed, ignored, mirrored, or promoted elsewhere.
• ephemeral/ contains active implementation scratch such as RUN_LOG files, handoff notes, QA findings, recovery notes, evidence, and scratch analysis. Ephemeral means uncommitted and non-durable, not necessarily memory-only; these files may persist locally until the worktree is removed.

For the methodology progression and section table of contents, read zazz-methodology.md.

Repository Layout

.agents/skills/        shared Zazz skills, kept AI-tool agnostic
docs/                  supporting methodology docs and guides
docs/standards/        reusable software engineering standards
templates/             example files for repos adopting the methodology
zazz-methodology.md    methodology overview and section table of contents
docs/methodology/      focused methodology section docs

Methodology Library

The methodology is split so teams can read only the part of the progression they are working on:

Stage	Document
Executive overview and table of contents	zazz-methodology.md
Document storage	docs/methodology/document-storage.md
Project orientation	docs/methodology/project.md
Architecture direction	docs/methodology/architecture.md
Proposals and decisions	docs/methodology/proposals.md
Features and project milestones	docs/methodology/features-and-milestones.md
Deliverable specifications	docs/methodology/specifications.md
Spec-driven development	docs/methodology/spec-driven-development.md
Deterministic quality gates and standards conformance	docs/methodology/deterministic-quality.md
Code generation	docs/methodology/code-generation.md
Testing and validation	docs/methodology/testing-and-validation.md
PR creation	docs/methodology/pr-creation.md
Automated self-review	docs/methodology/self-review.md
Human review and merge	docs/human-in-loop-pr-review-strategy.md

Each section includes a Relevant Skills table that explains which skills apply and how they improve process efficiency.

Standards Library

Start with docs/standards/README.md. The standards library is also indexed by docs/standards/index.yaml so agents can load the smallest relevant standard set for a task.

The standards are baseline templates for efficient AI-assisted software product development, not a universal corporate policy. Teams adopting Zazz should keep the generic methodology standards, replace stack-specific examples that do not fit, and add their own requirements for security, privacy, compliance, accessibility, release management, code ownership, and review evidence. The important habit is to make engineering expectations explicit enough that humans and agents can implement, test, and review against the same source of truth.

Recommended adoption flow:

1. Copy or sync docs/standards/ into the adopting repository's docs root.
2. Read docs/standards/README.md and decide which standards are generic methodology rules for your team.
3. Treat Python, React, SQL Server, AWS Lambda, GitHub Actions, and similar documents as stack-specific baseline examples. Keep them only when they match your architecture, or replace them with equivalent standards for your stack.
4. Update docs/standards/index.yaml so applies_to.paths, applies_to.activities, and purpose match the adopting repository.
5. Run a sensitive-reference scan before publishing the adapted standards. At minimum, search for personal names, local checkout paths, restricted project names, restricted repository URLs, and examples that only make sense in the source repository.
6. Add any organization-specific approval, compliance, security, privacy, accessibility, support, and evidence requirements that are required before merge.

Area	Standards
Core structure and docs	Generic baseline: code-structure.md, agent-skills.md, contextual-split.md, docs-hygiene.md, docs-hygiene-reference-structure.md, spec-hygiene.md, pr-process.md
HTTP/API layer	Stack-specific baseline example: http-layer.md, http-layer-guide.md, http-layer-schemas-and-responses.md, http-layer-errors-and-auth.md, http-layer-docs-and-tests.md
Service layer	Stack-specific baseline example: service-layer.md, service-layer-guide.md, service-layer-data-and-exceptions.md, service-layer-modules-and-cli.md
Data layer	Stack-specific baseline example: data-layer.md, data-layer-guide.md, data-layer-exec-sproc.md, data-layer-results.md, data-layer-errors.md, data-layer-templates.md, data-layer-utilities.md, data-layer-sproc-examples.md
Database	Stack-specific baseline example: database.md, database-guide.md, database-sproc-shape.md, database-sproc-errors.md, database-migrations-and-modernization.md, database-modernization-approach.md, database-testing.md, database-testing-guide.md
Frontend	Stack-specific baseline example: frontend.md, frontend-admin-crud-guide.md, frontend-forms-ui.md, frontend-hook-design.md
Testing and reports	Stack-specific baseline example: python-testing.md, python-testing-guide.md, python-testing-http-behavior.md, report-test-strategy.md, reports.md
Operations, tooling, and security	Mixed generic and stack-specific baseline: ci-workflows.md, ci-llm-conformance-workflows.md, deployment.md, backend-entrypoint-initialization-guide.md, backend-lambda-deployment-guide.md, logging-observability.md, logging-runtime-behavior.md, settings.md, security.md, tooling-hooks-and-formatters.md, tooling-lint-format.md

Skill Inventory

Customizing skills

These shared skills are baseline workflow implementations. Teams adopting Zazz can customize them for their technology stack, coding languages, architecture, review workflow, ticketing system, and PR tooling. Keep those customizations anchored to the repo's standards and local instructions so agents apply documented team rules instead of personal or tool-specific preferences.

Creating or updating shared skills? Follow agent-skills.md for the portable .agents/skills/<skill-name>/SKILL.md structure, front matter, metadata, description, and validation rules.

Interactive skills

Skill	Purpose
proposal-builder	Facilitates proposal discussions and drafts decision-ready proposals.
feature-doc-builder	Creates and evolves feature requirements documents for long-lived capabilities; the skill keeps its historical name for compatibility.
architecture-doc-builder	Creates and evolves project-level or feature-level architecture documents.
spec-builder	Guides bounded deliverable specification authoring, including prescriptive execution sequence and implementation guidance.
spec-driven	Guides the post-greenlight lifecycle: implementation loops, steering, contract updates, QA/PR feedback, and signoff.
gh-wiki	Placeholder workflow guidance for GitHub Wiki-backed durable docs and completed-spec promotion.
confluence	Placeholder workflow guidance for Confluence-backed durable docs and completed-spec promotion.
standard-builder	Inspects an existing codebase and drafts repo-specific standards for team review.

Execution and verification skills

Skill	Purpose
qa-testing	Runs verification against requirements, standards, tests, frontend/backend behavior, API checks, and evidence quality.
pr-review	Reviews PRs or local diffs for correctness, evidence quality, low-value tests, generated-code clutter, redundancy, and scope drift.

Delivery and infrastructure skills

Skill	Purpose
pr-builder	Produces draft-first PR packaging from diff, docs, stack context, and evidence.
gh-stack	Manages stacked branches and dependent PRs for incremental review workflows.
worktree	Sets up or manages the methodology's Zazz-style worktree model through the Worktrunk workflow used by the skill.
handoff	Creates temporary HANDOFF documents under <DOCS_ROOT>/ephemeral/ so a fresh agent or developer can continue safely.
zazz-board	Companion utility skill for Zazz Board integration.
jira	Draft companion utility for Jira-backed repos.
gh-issue	Companion utility skill for creating, reading, commenting on, and routing GitHub Issues when a repo uses GitHub issue tracking.
conformance	Applies one focused standards-alignment change against a named standard and bounded repo area, then prepares verified, self-reviewed PR evidence.
doc-check	Runs repo-local formatting and linting checks for documentation changes.
psql	Provides safe PostgreSQL diagnostic and profiling command guidance for repos that use psql.
sqlcmd	Provides safe SQL Server diagnostic command guidance for repos that use sqlcmd.

Setup and Prerequisites

Before adopting Zazz in a repo, make sure the team has the supporting tools and repo entry points the methodology expects:

• Git: required. Zazz uses branches, worktrees, commits, diffs, and PRs as core collaboration primitives. Install it through the normal path for your platform, such as Apple Command Line Tools on macOS, a Linux package manager, Git for Windows, or the downloads linked from git-scm.com.
• Git hosting and PR tooling: required for normal team use. GitHub is common, but the methodology also works with GitLab, Bitbucket, Forgejo, or another Git-based review system.
• GitHub CLI (gh): recommended when the repo uses GitHub, PR automation, or gh-stack. Install from cli.github.com and run gh auth login before expecting agents to create or inspect PRs.
• Worktrunk: recommended for routine worktree management and required by the bundled worktree skill. Native git worktree remains the base capability. Install from worktrunk.dev.
• gh-stack: optional, but recommended when the team wants stacked PR lanes. Install the GitHub CLI extension from github/gh-stack; command reference lives at github.github.com/gh-stack.
• Agent runtime: required. Use Codex, Claude, Cursor, Warp, or another agent environment that can read repo instructions and load skills.
• Project runtime/toolchain: required for real execution. Install the repo's normal language runtimes, package managers, test tools, database services, and local environment helpers before asking agents to implement or verify work.
• Node.js: required when using the bundled zazz-board CLI helper, because zazzctl is a Node-based script.
• External tracker, wiki, or knowledge base: optional. Zazz Board can centralize run logs, handoff notes, QA findings, file locks, and task state, and may mirror specification metadata when the repo declares that. GitHub Wiki or Confluence can hold durable project knowledge and final implemented specs. Repos may also operate entirely from Git plus <DOCS_ROOT>/ephemeral/.

Common setup commands:

gh auth login
gh extension install github/gh-stack

Recommended repo-local setup:

repo/
├── AGENTS.md
├── .agents/
│   └── skills/
└── <DOCS_ROOT>/
    ├── project.md
    ├── standards/
    ├── features/
    ├── architecture/
    ├── specifications/
    └── ephemeral/

Keep <DOCS_ROOT>/specifications/ available in the local worktree so implementation agents can read and execute the specifications authored by spec-builder. Track, ignore, mirror, or promote it according to the repo's operating model.

Use .agents/skills/ as the canonical repo-local skill location when vendoring Zazz skills into a project. Runtime-specific instruction files can either point agents at .agents/skills/ or copy/sync selected skills into the runtime's native skill directory.

Getting Started

If you are adopting the methodology in another repo:

1. Read zazz-methodology.md, then follow the section links that match your current workflow.
2. Review templates/AGENTS.md because AGENTS.md declares repo-specific settings such as docs root, tracking system, branch policy, and review workflow.
3. Install the supporting tools your workflow needs: Git, Worktrunk, gh, gh-stack, and any project-specific build/test tools.
4. Read docs/worktree-setup.md because the methodology requires the worktree operating model.
5. Copy or sync the skills you want from .agents/skills/ into the repo or your agent runtime.

Installing Skills

The shared skills live under .agents/skills/ so they stay AI-tool agnostic.

Common installation patterns:

• copy them into a runtime skill directory such as $CODEX_HOME/skills/
• vendor them into another repo's .agents/skills/
• point runtime-specific instruction files at the repo's .agents/skills/ directory when the runtime supports that pattern
• sync this repo into downstream methodology consumers

Historical naming note:

• feature-doc-builder remains the skill name for compatibility, but the methodology's canonical artifact term is feature requirements document

Artifact Storage

Zazz is Git-native, but durable project docs do not always have to be committed Markdown files in the application repo. Repos declare their document storage policy in AGENTS.md.

Supported durable surfaces:

• repo-committed Markdown reviewed through PRs
• GitHub Wiki, GitLab Wiki, Bitbucket Wiki, or another repo wiki
• Confluence, SharePoint, Google Docs, Notion, or a similar knowledge base
• tracker-backed records such as Zazz Board or Jira

Repos choose and document their active-artifact policy in AGENTS.md:

• Proposals live under <DOCS_ROOT>/proposals/ by default, but may live in Google Docs, SharePoint, Confluence, or another shared document system when rich images, screenshots, diagrams, comments, or non-engineering stakeholder review make that the better collaboration surface. In that case, keep a stable pointer under the declared docs entry point.
• Deliverable specifications live under <DOCS_ROOT>/specifications/ so Contributor Agents can execute the current spec from the local worktree. The operating model decides whether those files are committed, ignored, mirrored to Zazz Board/Jira, or promoted after merge to GitHub Wiki, Confluence, or another declared durable surface.
• RUN_LOG files and active execution records live under <DOCS_ROOT>/ephemeral/ when kept on disk. This directory usually stays out of Git and holds run logs, handoff notes, QA findings, recovery notes, evidence, and related active-work records.
• Teams that do not use Zazz Board can rely exclusively on <DOCS_ROOT>/ephemeral/ for local active implementation records.
• Teams that use Zazz Board may use it as the centralized execution-record service so multiple agents can share run logs, handoff documents, QA findings, task state, specification metadata, and related information across worktrees and sessions.

Propagation

This repo is meant to be copied or synced outward. Downstream repos should not become the authoritative source for shared methodology intent.

Example:

rsync -avc /path/to/zazz-skills/zazz-methodology.md /path/to/consumer-repo/zazz-methodology.md
rsync -avc --delete /path/to/zazz-skills/.agents/skills/ /path/to/consumer-repo/.agents/skills/
rsync -avc --delete /path/to/zazz-skills/docs/ /path/to/consumer-repo/docs/

Changelog

2026-08-01 — Portable skill metadata and lighter repository guidance

Hardened all shared skill front matter against YAML parsing failures by standardizing safe description quoting and adding portable validation guidance. Updated the Agent Skills standard with cross-runtime authoring and skill-admission rules, removed runtime-specific assumptions from shared review and GitHub Issue workflows, and replaced the large AGENTS.md example with a lightweight routing template. Added an ignored local scratch area and a handoff for the separately scoped standards-library analysis.

2026-07-03 — Ephemeral and wiki-backed docs model

Added the optional durable storage model for repo Markdown, GitHub Wiki, Confluence, and tracker-backed records. Specifications remain local working files under <DOCS_ROOT>/specifications/, with the repo deciding whether that directory is tracked, ignored, mirrored, or promoted elsewhere. RUN_LOG files, QA notes, handoffs, recovery notes, evidence, and scratch artifacts now default to <DOCS_ROOT>/ephemeral/.

2026-06-18 — Public methodology and standards refresh

Split the methodology into a concise executive overview plus focused workflow sections, refreshed the README with the current skill and standards inventory, consolidated QA guidance under qa-testing, and added PostgreSQL/SQL Server diagnostic utility skills.

2026-05-24 — Execution artifact location refresh

Renamed the default local active execution artifact directory to <DOCS_ROOT>/ephemeral/, and clarified that Zazz Board can serve as the centralized execution-record surface for run logs, handoff documents, QA findings, and related information shared across worktrees, agents, and sessions.

2026-05-23 — Methodology and skill alignment refresh

Aligned the methodology, README, supporting docs, and shared skills around feature, architecture, and specification document locations; draft-first PR packaging; stacked PR lanes; Zazz Board or Git-backed specification storage; and direct skill customization.

License

See LICENSE.