Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
129 lines (96 loc) · 7.76 KB

CONTRIBUTING.md

File metadata and controls

129 lines (96 loc) · 7.76 KB
Raw

Contributing to Fab Kit

Documentation Structure

Fab Kit's documentation is split into two categories:

  • docs/specs/ — Pre-implementation design specs. Human-curated, captures the "why" behind features. Organize however makes sense.
  • docs/memory/ — Post-implementation memory files. AI-maintained via hydration, authoritative source of truth for system behavior.

Reading Paths

Contributor — "I want to modify or extend Fab Kit"

  1. docs/specs/overview.md — workflow design and principles (prerequisite for everything)
  2. docs/specs/glossary.md — terminology you'll see everywhere
  3. fab/project/constitution.md — immutable project principles (MUST/SHOULD rules)
  4. docs/specs/architecture.md — directory structure, config, naming, agent integration
  5. docs/specs/skills.md — detailed behavior for each /fab-* skill
  6. docs/memory/distribution/kit-architecture.md — kit distribution: the system cache (~/.fab-kit/versions/<version>/kit/), fab sync, deployment
  7. docs/specs/templates.md — artifact template system
  8. docs/memory/pipeline/schemas.md — pipeline stage schemas and .status.yaml development guide

Spec Reader — "I want to understand the design rationale"

  1. docs/specs/glossary.md — read this first to understand the vocabulary
  2. docs/specs/overview.md — high-level design, principles, stage definitions
  3. docs/specs/architecture.md — structural decisions and conventions
  4. docs/specs/skills.md — skill-by-skill behavioral specification
  5. docs/specs/templates.md — template design and field semantics
  6. docs/specs/user-flow.md — visual command flow diagrams

Document Inventory

Getting Started

Document Description
docs/specs/overview.md The Fab workflow specification — design principles, 6 stages, quick command reference
docs/specs/user-flow.md Visual diagrams showing how commands connect and how a typical development session flows
docs/specs/glossary.md All Fab terminology — core concepts, stages, skills, files, SRAD, conventions
docs/memory/distribution/setup.md /fab-setup — structural bootstrap: creates config.yaml, constitution.md, directories
docs/memory/_shared/configuration.md config.yaml schema and constitution.md governance

Concepts

Document Description
fab/project/constitution.md Project principles and constraints — the MUST/SHOULD rules that govern all skills
docs/memory/pipeline/change-lifecycle.md Change folders, .status.yaml, naming conventions, git integration, /fab-status, /fab-switch
docs/memory/_shared/context-loading.md How skills load project context — always-load layer, selective domain loading, SRAD protocol
docs/memory/memory-docs/hydrate.md /docs-hydrate-memory — dual-mode: ingest external sources or generate docs from codebase scanning
docs/memory/memory-docs/specs-index.md docs/specs/ directory — pre-implementation specs, distinction from docs

Reference

Document Description
docs/specs/skills.md Detailed behavioral specification for each /fab-* skill
docs/memory/pipeline/planning-skills.md /fab-new, /fab-discuss, /fab-continue, /fab-ff, /fab-clarify — the planning pipeline
docs/memory/pipeline/clarify.md /fab-clarify — dual modes (suggest/auto), taxonomy scan, structured questions
docs/memory/pipeline/execution-skills.md Apply, review, archive behavior — accessed via '/fab-continue'
docs/memory/memory-docs/hydrate-specs.md /docs-hydrate-specs — structural gap detection between memory and specs
docs/specs/templates.md Artifact templates — intake, plan (requirements + tasks + acceptance), status
docs/memory/memory-docs/templates.md Template implementation details and centralized doc format

Internals

Document Description
docs/specs/architecture.md Directory structure, config schema, naming conventions, agent integration
docs/memory/distribution/kit-architecture.md Kit distribution — system cache (~/.fab-kit/versions/<version>/kit/), fab sync deployment, agent integration
docs/memory/pipeline/preflight.md fab preflight — validation, structured YAML output, skill integration
docs/memory/memory-docs/hydrate-generate.md /docs-hydrate-memory generate mode — codebase scanning, gap detection, doc generation

Index Files

Index What it covers
docs/specs/index.md Pre-implementation specifications (design intent)
docs/memory/index.md Post-implementation centralized docs (what actually shipped)
docs/memory/index.md Domain index — links to each domain (pipeline, memory-docs, distribution, runtime, _shared); per-domain indexes list files with last-updated dates

Stage State & Queries (fab CLI)

Stage state lives in each change's .status.yaml and is owned by the fab Go binary (source in src/go/fab/). The pipeline is six stages: intake → apply → review → hydrate → ship → review-pr.

# Resolve + summarize the active change (YAML: id, name, change_dir, stage, display_stage, display_state, progress, plan, confidence)
fab preflight

# Stage queries
fab status all-stages                     # List stage IDs in order
fab status progress-map <change>          # stage:state pairs
fab status current-stage <change>         # Detect active stage
fab status validate-status-file <change>  # Validate .status.yaml against the schema

# Stage transitions (state machine)
fab status start|advance|finish|reset|skip|fail <change> <stage>

Development & Testing:

# Run the Go test suite
cd src/go/fab && go test ./...

For complete documentation, see:

Creating a Release

To publish a new release:

release.sh [patch|minor|major]
  • patch (default): 0.1.0 → 0.1.1
  • minor: 0.1.0 → 0.2.0
  • major: 0.1.0 → 1.0.0

The script will:

  1. Bump the version in src/kit/VERSION
  2. Commit the VERSION bump, tag, and push
  3. Create a GitHub Release with kit.tar.gz as an asset

Requires: clean working tree, gh CLI, and a configured origin remote.