CONTRIBUTING.md

Contributing to Agentweaver

Thanks for considering a contribution! This doc is the contribution process guide — how to make a change and get it merged. It has two parts:

• Dev environment & reference (setup, repo layout, testing, code style) — the quick version lives here, but the canonical, in-depth environment setup guide is Getting started (prerequisites, per-platform installs, local run, OAuth config). This doc does not duplicate it — it points to it and adds only the repo conventions a contributor needs.
• Contribution workflow (Making a change, Continuous integration, Opening a pull request, Commit messages, AI agent contributions) — how a change actually lands. For the release/versioning process, see RELEASING.md.

Prerequisites

See Prerequisites in the getting started guide for the tools you'll need (git, Node.js 22+, .NET 10 SDK, and Azure CLI if you're touching the provisioning/deployment scripts) and per-platform install instructions (winget/brew/apt-get).

Getting set up

git clone https://github.com/sabbour/agentweaver.git
cd agentweaver
npm run setup   # checks/prepares local prerequisites (git, dotnet, node)
npm run dev     # starts the API (http://localhost:5000) and Web UI (http://localhost:5173)

See the Getting started guide for the full walkthrough, including Microsoft Entra configuration for local product sign-in. GitHub Repo App and Copilot App connections grant optional, purpose-bound capabilities; they are not Agentweaver sign-in providers.

Repository layout

Path	What it is
apps/Agentweaver.Api	The .NET API (coordinator, runs, memory, auth, sandbox orchestration)
apps/Agentweaver.Mcp	The MCP server surface
apps/web	The React/Vite frontend
docs/	VitePress documentation site (published at sabbour.me/agentweaver)
packages/	Shared .NET libraries (agent runtime, squad model, etc.)
scripts/azure	The Node.js provisioning/deployment/release toolchain (no bash/PowerShell)
tests/Agentweaver.Tests	.NET test suite
tests/e2e	End-to-end tests
k8s/	Kustomize-based Kubernetes manifests (AKS deployment): k8s/base/ (generic manifests), k8s/overlays/production/ (image tags, ConfigMap/replacements patches), k8s/reference/ (non-deployed examples/one-off jobs)

Making a change

1. Use a short-lived branch and PR for every change. dev is the default, protected integration branch. Branch from current origin/dev with a descriptive conventional prefix, e.g. fix/123-short-desc, feat/short-desc, or docs/short-desc.
   • Direct pushes to dev are not allowed, including tiny and docs-only changes.
   • Before merge, the branch must be current with dev and all blocking CI must rerun successfully. GitHub enforces this through “require branches to be up to date before merging.”
   • Before ready and immediately before merge, Ralph fetches origin/dev, gets the live PR headRefOid, and runs the external-state preflight with that SHA: node scripts/ci/squad-admission-preflight.mjs <owner/repository> <pr-number> --head-sha <live-head-sha>. The preflight resolves the declared external Squad state with the pinned Squad SDK and validates its coordinator-owned findings ledger. Ralph records the returned <validated-sha> and merges manually with gh pr merge <number> --squash --match-head-commit <validated-sha>. GitHub automatically deletes the source branch after merge.
   • main is stable/published-only. Do not open ordinary PRs into it; it receives a soaked release promotion or an audited emergency hotfix only. A release promotion may use a merge commit when repository policy permits it.
   • Do not create a long-lived local integration/staging branch as a private promotion pipeline. A disposable merge-test branch or worktree is fine, but delete it after validation.
2. Keep changes focused. Scope one change to one concern — it's easier to review and to revert if something goes wrong.
3. Add or update tests for any behavior change (see Testing below).
4. Update docs if you changed user-facing behavior, npm scripts, or configuration — README.md and docs/guide/ are the two places most likely to need updates. If documentation changes introduce, update, invalidate, consolidate, or remove an architectural/process visual, consider and invoke the on-demand docs diagram audit skill. Use docs-diagram-pitch and docs-diagram-iterate for the resulting individual diagrams.
5. Run the relevant test suite(s) locally before you push. CI re-runs the full suite on every pull request and push to dev or main, but running the affected suite locally first keeps the feedback loop short and avoids red PRs.
6. Add a changeset for shipped user-facing behavior before opening the PR: run npm run changeset, use patch for compatible fixes and minor for features or breaking changes while Agentweaver is at 0.x, and write prose for users rather than restating a commit title. Do not edit VERSION, package versions, or CHANGELOG.md. Docs/tests/CI-only changes normally need no changeset; use the changeset:not-required label only with a Changeset exemption: rationale in the PR body. Infrastructure and local deployment commands never consume changesets; release:publish consumes only metadata already prepared by release:prepare. The Changeset advisory CI job blocks merge if it detects a release-relevant change with no changeset and no exemption, so this can't be silently skipped. For the full playbook, see the changelog skill.
7. Verify live for anything with runtime/deploy impact, not just via unit tests.

Writing a changeset

Good: “Add exportable workflow bundles so operators can move a workflow between installations.”

Bad: “feat: add export.” It repeats a commit title without explaining the user impact.

Branch Topology

The active topology is dev → release/vX.Y.Z → main:

• dev is the default, protected integration branch. Normal PRs target it and use required PRs, blocking CI, an external-state exact-head admission preflight, manual squash merge, and automatic source branch deletion.
• release/vX.Y.Z is an ephemeral release-candidate/soak branch cut from a green dev SHA. Stabilization fixes land there by PR and are immediately forward-ported to dev.
• main is stable/published-only. It receives only a promotion PR from a soaked release branch or an audited emergency hotfix, which must be forward-ported to dev. Release tags are cut from the exact resulting main promotion SHA.

The complete operating flow is in RELEASING.md.

Temporary integration branch queue

GitHub Merge Queue is not currently available for this repository. Independent PR cohorts may instead use one published, short-lived integration branch as a serialized admission queue; it must not reuse a release branch. The canonical queue contract, Ponytail gate, aggregate debt capture, and promotion rules are in gh-stack parallel work. gh stack v0.1.0 remains optional only for genuinely dependent, strictly linear PR layers, never as the independent-issue queue.

Testing

Prepare dependencies once per worktree. Every package root keeps a physical, private node_modules; developer worktrees share only a fingerprinted npm download cache under Git's common directory. A new worktree still runs reproducible npm ci, while an unchanged local tree is verified and reused. CI, npm workspaces/local links, and authenticated npm configuration use isolated npm ci:

npm run deps:ensure

For an ordinary branch or a layer in a stacked change, run only the affected areas:

npm run validate:layer

# .NET changes require a focused VSTest filter at layer level.
npm run validate:layer -- --area dotnet \
  --dotnet-filter "FullyQualifiedName~Agentweaver.Tests.Coordinator"

The layer profile detects Node toolchain, web, docs, and .NET paths relative to origin/dev. It runs web tests and lint after one dependency setup. A .NET layer must name a focused filter. The layer check is advisory; each PR still receives required CI. NuGet packages are shared by the user cache, while locked restore, build output, and tests remain worktree-local.

At the top of a completed stack, run the full profile against the exact integrated tree. PR 1 must independently pass the full suite against its current dev merge candidate before merge; a green stack top is not a substitute:

npm run validate:full

The underlying area commands remain available for focused troubleshooting:

# .NET API / packages: locked restore, one build, then test exact outputs
dotnet restore tests/Agentweaver.Tests/Agentweaver.Tests.csproj --locked-mode -p:CopilotSkipCliDownload=true
dotnet build tests/Agentweaver.Tests/Agentweaver.Tests.csproj --no-restore -p:CopilotSkipCliDownload=true
dotnet test tests/Agentweaver.Tests/Agentweaver.Tests.csproj --no-build --no-restore -p:CopilotSkipCliDownload=true

# Node.js provisioning/deployment/release toolchain and CI contracts
node --test scripts/azure/tests/*.test.mjs scripts/changesets/tests/*.test.mjs scripts/ci/tests/*.test.mjs

# UI harness fixture/regression suite
node scripts/ci/shared-deps.mjs ensure --project scripts/ui-harness
npm --prefix scripts/ui-harness test

# Web frontend typecheck
npm --prefix apps/web run typecheck

# Web frontend (Vitest)
npm --prefix apps/web run test

# Web frontend lint
npm --prefix apps/web run lint

# Machine-generated coverage reports. These do not prove behavioral completeness.
npm run coverage:dotnet
npm run coverage:web
npm run coverage:node
npm run coverage:all

# Docs site build (only if you changed docs/)
npm run docs:build

Published documentation

.github/workflows/deploy-docs.yml is the only GitHub Pages publisher. It publishes 0.x at /agentweaver/ and v1 at /agentweaver/v1/. The workflow combines the 0.x build with an artifact from the current v1 branch head. It accepts only a successful push run to that head from sabbour/agentweaver. It records the v1 source commit, run, attempt, and artifact ID in the workflow summary. The composer leaves the 0.x output in place, including CNAME when present. If no matching artifact exists, the build stops before deployment. Do not add a second Pages deployment.

See Validation workflow for cache keys, invalidation, fallback behavior, and timing output.

Continuous integration

Pull requests and pushes to dev and main are verified by the CI workflow. It runs the same commands documented under Testing above, split into one job per area so each gets a dedicated runner (several .NET and web tests are timing-sensitive and flake under CPU contention if crowded onto a single runner). A changes job classifies each diff by path first, and every suite job below except Changeset advisory only runs when its path group actually changed (any edit to .github/workflows/ci.yml itself always runs everything, so the pipeline is always fully verified when it changes; edits to other workflow files don't run these suites, since they don't drive them); a job that's skipped this way still counts as passing for required-status-checks purposes:

Job	What it runs	Gating	Runs when
Seven .NET test shard (…) jobs	Stable namespace shards plus isolated PostgreSQL/Testcontainers, process-global environment, and Kata runtime gates; every shard writes TRX results	Blocking — must pass	Every PR targeting dev, so all seven ruleset-required contexts are emitted even for metadata-only PRs
Node toolchain tests	Full Node toolchain/CI-helper tests plus npm --prefix scripts/ui-harness test	Blocking — must pass	Node toolchain paths or UI harness/shared harness paths changed
Web tests	Web typecheck, tests, and lint after one isolated npm ci	Blocking — must pass	apps/web/** changed
Docs build	npm run docs:build	Blocking — must pass	docs/** changed
Documentation diagrams	Generator tests and rendered-artifact stamp checks	Workflow validation	Diagram tooling/assets changed, as classified by ci.yml
Changeset advisory	npm run version:check && npm run changeset:check	Blocking — must pass	Always, on every PR

The repository policy requires the seven named .NET shard jobs plus the Node toolchain, web, docs, and changeset jobs on a branch that is up to date with dev. Path-conditional non-.NET jobs count as passing when skipped; the named .NET shard jobs intentionally run on every dev PR so GitHub emits each required context. The GitHub ruleset described in .github/dev-branch-protection.md provides ordinary branch and CI protection. Squad/Ralph external-state preflight owns admission: the Coordinator/Ralph process and authoritative external Squad state are trusted operational components, while GitHub supplies PR evidence and CI only. Repository code does not create an adversarially immutable execution boundary. The coordinator must validate the closed findings policy and ledger state at the live head before manual squash merge. Changeset advisory now fails the build (not just a warning) when a release-relevant change has no changeset and no changeset:not-required exemption.

CI is the full-suite authority and deliberately keeps job filesystems isolated. Its npm steps call the same dependency helper with --isolated, preserving npm ci reproducibility. Local concurrent worktrees share only npm download content; writable dependency trees and build/test outputs never cross worktree boundaries.

Scheduled coverage reports

Coverage collection is not a separate workflow — it is the same dotnet-test-shards, web-tests, and node-toolchain-tests jobs in CI that every PR already runs, instrumented in place. A weekly schedule (Mondays 05:00 UTC) and an opt-in collect_coverage workflow_dispatch input both set a collect_coverage job output that (a) forces those three jobs to run regardless of path filters or draft state, and (b) threads a coverage flag into the same single dotnet test / vitest / node --test invocation each job already performs — never a second test run. Ordinary pull_request/push events never set this flag, so their command lines stay byte-identical to the pre-coverage behavior. Each area's job still fails honestly when its coverage run is partial (an unsupported Kata/Postgres shard, a timed-out shard, etc.), and uploads its report with bounded (14-day) retention via if: always(). Two additional jobs run only when collect_coverage is true: dotnet-coverage-combine downloads the per-shard .NET artifacts produced in the same run and merges them, and coverage-summary renders measured per-area totals and gaps to the run's job summary without applying any coverage threshold. See Coverage reports for the full report layout and the workflow_dispatch default-branch requirement.

Container image publishing

The Publish images workflow builds the four Agentweaver container images and publishes them to GitHub's container/artifact registry (ghcr.io/<owner>/agentweaver-{api,frontend,mcp,agent-host}). It never deploys anything — Azure/AKS deployment stays with the npm run azure:* toolchain.

The image list is not restated in the workflow: the plan job derives its build matrix from scripts/azure/image-spec.mjs (the deploy toolchain's single source of truth) through scripts/ci/ghcr-plan.mjs, which is unit-tested by the Node toolchain tests job. Triggers map to the branch topology above:

• push to dev → :sha-<short> and :dev
• push to release/vX.Y.Z → :sha-<short> and :rc-X.Y.Z
• push to main → :sha-<short> and :main
• tag push vX.Y.Z → :sha-<short>, :X.Y.Z, :vX.Y.Z, and :latest
• manual workflow_dispatch → :sha-<short> plus the selected ref's channel tag for dev, main, or release/vX.Y.Z; other refs receive only :sha-<short>. An optional build-only dry run skips the push

Pull requests do not trigger image builds; ordinary PR validation is provided by the CI workflow. Release images are built and published by the vX.Y.Z tag push that npm run release:publish creates.

Every build publishes the immutable sha-<short> tag, so any image is addressable by the exact commit it was built from — the same identifier model npm run azure:deploy-from-local and azure:deploy-from-commit use. npm run release:publish pushes the tag first. It waits for Publish images to build the tag images before it creates the GitHub Release.

Opening a pull request

• Keep the PR scoped to one concern and give it a conventional-commit-style title (see Commit messages) — the title is what shows up in the generated changelog and the GitHub Release notes.
• Describe what changed and why, and how you verified it (which suite(s) you ran, and any live/deploy verification for runtime changes).
• Make sure the blocking CI jobs are green and that you have not introduced new lint findings before asking for review.
• Update, retest, then merge manually: If another PR reaches dev first, update from origin/dev, resolve conflicts, rerun relevant tests/CI and the external-state preflight, then use gh pr merge <number> --squash --match-head-commit <validated-sha>.

Target release milestone

Set a GitHub milestone on every pull request and on every issue you plan to fix. The milestone names the release that will carry the work, such as v0.32.4. Use the next unreleased patch version. If you do not know the target version, use the open milestone with the lowest version number.

gh pr edit <number> --milestone "v0.32.4"
gh issue edit <number> --milestone "v0.32.4"

The milestone answers two questions that the changelog cannot answer on its own: what a given release contains before it ships, and which release carried a given fix after it ships. Use it to report status:

gh pr list --search "milestone:v0.32.4"          # what is planned or shipped
gh issue list --milestone "v0.32.4" --state all  # what this release repairs

A milestone is a target, not a guarantee. Merge order decides the real contents. A PR that misses the release cut ships in the next release, even when the milestone still names the earlier one. The release manager reconciles the milestones against the changesets the release actually consumed. See RELEASING.md → Preparing a release. Set your best estimate and let that reconciliation correct it.

Rules:

• The release manager creates the next milestone when a release is cut, and closes the milestone after the release publishes.
• Move work that slips to the next milestone. Do not leave it on a closed one.
• A milestone records the target release. The release:blocking and release:backlog labels record triage intent. The two are complementary. Do not use the legacy release:v0.x version labels for this. They stop at v0.10 and are not maintained.

Contributing from a fork

Fork the repository on GitHub, clone your fork, add the canonical repository as the upstream remote, and create your short-lived branch from an up-to-date upstream/dev. Open the PR from that branch to dev; it follows the same CI, up-to-date, review, external-state preflight, and manual squash-merge rules as every other contribution.

Fork PRs do not receive repository secrets: CI uses the pull_request trigger (not pull_request_target) and its jobs do not use secrets.*. CODEOWNERS and a required approval for non-owner PRs are not active today. On the first real external fork PR, audit the fork workflow again, then add/activate those controls as a checklist item; do not assume they already exist.

Labels

.github/labels.json is the canonical taxonomy for new and relabeled issues. Use one type:*, priority:*, go:*, and release:* label where applicable; use squad:{member} for ownership and an optional area:* label for product scope. sync-squad-labels.yml reads that manifest for static labels and generates squad member labels from the roster. The legacy bug, enhancement, and workstream:* labels are deprecated in favor of type:bug, type:feature, and the smaller area:* vocabulary; existing issues are not being mass-relabelled.

The legacy release:v0.x version labels are also deprecated. They stop at v0.10 and do not track patch releases. Use a target release milestone instead. Keep release:blocking and release:backlog, which record triage intent rather than a target version.

Commit messages

Changesets generates new CHANGELOG.md sections from reviewed release-note fragments. Please use a conventional-commit-style prefix:

• feat: ... — new functionality
• fix: ... — bug fixes
• docs: ... — documentation-only changes
• chore: ... / refactor: ... — internal changes with no user-facing behavior change
• test: ... — test-only changes

Code style

• .NET: follow the existing conventions in the file/module you're editing. Don't introduce a new formatting style into an existing file.
• .NET dependencies: every project restores with RestorePackagesWithLockFile=true (see Directory.Build.props) and commits a packages.lock.json, and CI restores with RestoreLockedMode=true so an unreviewed dependency version change fails the build instead of silently resolving a newer package. Use exact PackageReference versions (no floating 1.* or open ranges) for new/changed dependencies. After adding, removing, or changing a package version, regenerate the affected lock file(s) with dotnet restore --force-evaluate and commit the updated packages.lock.json alongside the .csproj change.
• Node.js (scripts/azure/): ESM (.mjs), no bash/PowerShell — this toolchain is intentionally 100% cross-platform Node.js (it fully replaced the earlier bash/PowerShell scripts). Read the module header comment at the top of the relevant scripts/azure/*.mjs file before changing behavior — several non-obvious ordering/timing decisions are documented there specifically to avoid reintroducing past bugs.
• Web: TypeScript + React, FluentUI components. Run npm --prefix apps/web run lint before submitting.

Where NOT to make changes

• Do not hand-edit generated CHANGELOG.md release sections; add or correct the source changeset instead.
• Do not add build/deploy logic outside scripts/azure/ — bash/PowerShell scripts were fully removed in favor of the Node.js toolchain; don't reintroduce a second toolchain.
• Do not commit secrets (API keys, GitHub OAuth client secrets, connection strings) — appsettings.Development.json is git-ignored for local secrets; use .NET user-secrets or environment variables instead.
• Do not weaken auth/security checks (or otherwise take shortcuts) just to make a test or a manual verification pass — fix the real blocker instead.

AI agent contributions

Some contributions to this repo are made by AI agents rather than people. This project is developed with Squad, a team of named agents (Trinity, Tank, Morpheus, Smith, Link, Seraph, Scribe, Ralph, Rai, and others), and can optionally route work to GitHub's @copilot coding agent when it is on the roster. This section documents how that agent-driven flow works. It does not replace the human workflow above — human contributors follow the same branch → up-to-date PR → manual squash-merge path in Making a change and can skip this section.

Issue-driven lifecycle. Agent work is anchored to a GitHub issue and follows issue -> branch -> PR -> review -> merge. The label-based automation in .github/workflows/ drives it:

• sync-squad-labels.yml keeps the squad:{member} labels in sync with the roster in .squad/team.md.
• squad-triage.yml reacts to the squad label: the Lead agent routes the issue to a member (or to @copilot when it is a good fit), applies the squad:{member} label, and adds a default go:needs-research verdict.
• squad-issue-assign.yml reacts to a squad:{member} label by acknowledging the assignment (and, for squad:copilot, handing the issue to the @copilot coding agent).
• squad-label-enforce.yml enforces mutual exclusivity within the go:, type:, priority:, and release: label namespaces.

Feature and bug issue templates add the squad label by default, so the triage workflow routes them when filed. For issues filed outside those templates, add squad manually to request Squad routing. Triage is a lightweight operating norm rather than a hard SLA: handle P0 reports the same business day and route other new Squad issues within a few business days.

Before implementation dispatch, the Coordinator prepares the issue branch squad/{issue-number}-{slug} and a dedicated clean worktree, verifies that worktree's branch and CWD, and passes the absolute CWD to the assigned agent. The repository root is coordination-only when it is dirty or diverged: do not dispatch implementation from it. An agent commits the completed issue work on that branch before accepting another issue. After bounded independent review, it pushes and opens a draft PR with gh pr create against dev. Every delivery status reports the PR number (or no PR), branch, exact SHA, validation, and any blocker. The full lifecycle, spawn context, and merge commands live in .squad/templates/issue-lifecycle.md; the orchestration rules live in .github/agents/squad.agent.md. Agent PRs are gated by the same CI as everyone else's.

Branches vs. worktrees. A locally run Squad agent (including a Copilot CLI agent) must use one dedicated clean git worktree per issue under .worktrees/, reusing it when collaborating on that issue. Parallel implementation is permitted only when every participating worktree is clean, prepared, and on its assigned issue branch. A hosted agent (such as GitHub's @copilot coding agent) uses the platform's isolated branch and environment instead — no local worktree applies. Human contributors may use a worktree as a convenience, but a plain short-lived branch in the main checkout is supported. The creation, reuse, dependency, team-root, and cleanup mechanics live in .squad/templates/worktree-reference.md; do not duplicate them here.

New feature workflow. Proposing a new feature or capability (agent or human):

1. Open a GitHub issue first — no un-tracked feature work. Describe the user story/problem it solves.
2. Add or update a spec under specs/ before or alongside the code. Specs are area-grouped, one file per user story, each linking its GitHub issue number — follow the existing files' format exactly (title; **Issue:** + **Area:** header; ## User story, ## Context / problem, ## Scope (In/Out), ## Acceptance criteria, ## Notable edge cases), and add the story to the matching area section of specs/README.md.
3. Then follow the normal issue → branch → PR → review → merge lifecycle above, including updating user-facing docs (docs/guide/, README.md) in the same change as required by the Documenting your work guidance below.

New user-facing functionality that lands without a corresponding specs/ entry should be flagged in review. This is a convention, not an enforced gate: the docs-drift.yml nudge watches API/workflow/blueprint/ MCP code paths against docs/** only — it does not cover specs/, so nothing mechanically blocks a spec-less feature PR. Reviewers are responsible for catching it.

Bug-fix workflow. Fixing a bug (agent or human):

1. Open (or reuse) a GitHub issue describing the bug: repro steps and expected vs. actual behavior. Don't file untracked fixes for anything beyond a trivial/obvious one-liner (typo, broken link, obviously-wrong constant) — anything with behavioral nuance or a risk of regression gets an issue.
2. Reference the issue in the commit/PR with Closes #N (see Commit messages) so it auto-closes on merge. Set the target release milestone on both the issue and the PR (see Target release milestone).
3. Include a regression test that fails before the fix and passes after, whenever the bug is in code with a test suite — this is the existing "add or update tests for any behavior change" rule applied to fixes, and it is what QA (Smith's charter) means by preventing regressions. A fix with no test should say why one isn't feasible.
4. After merge, the same lifecycle applies: CI-gated, and the issue closes automatically via Closes #N (or close it manually if the fix only partially addresses the issue).

Peer review and the reviewer-rejection protocol. Changes requested is ordinary review feedback: the original author may revise the same PR normally, with no lockout. When a Reviewer (Tester, Code Reviewer, Lead, or Rai for Responsible AI) rejects an artifact, they provide evidence and a defined corrective scope for one bounded pass. The Coordinator uses one fresh agent context, which may use the original author's named agent and charter; it must not impose an original-author lockout or rotate charters as theater. The stated finding and its evidence are re-reviewed after the pass. The Coordinator posts a new revalidation comment under the PR Comment Writing Policy. The Coordinator escalates only when concrete design or safety risks remain unresolved. The full rules are in the "Reviewer Rejection Protocol" section of squad.agent.md.

Rubber-ducking. Before a non-trivial or risky change ships, the Coordinator can invoke a rubber-duck review pass — a dedicated critical-feedback agent whose only job is to hunt for bugs, logic errors, and design flaws before anything is committed. It is invoked at the Coordinator's discretion for higher-risk work, not automatically on every change.

Auditable decisions. Meaningful design decisions are recorded to the decisions inbox (.squad/decisions/inbox/); Scribe periodically merges routine operational decisions into the canonical .squad/decisions.md. Cross-cutting architecture or technical decisions that should survive that ledger's compaction are promoted to numbered ADRs. This keeps agent-driven changes traceable back to the reasoning behind them.

Documenting your work. Docs are part of the definition of done, not a follow-up. When a change affects user-facing behavior — npm scripts, CLI flags, setup/deploy steps, API routes or config, the OAuth flow — update the relevant docs in the same change: the VitePress guide under docs/guide/ (the source of truth for https://sabbour.me/agentweaver, built with npm run docs:build / docs:dev / docs:preview) and/or README.md (quick overview and links out). CONTRIBUTING.md and RELEASING.md are the process docs; add inline code comments only where they genuinely clarify intent (this repo's style avoids over-commenting). Some reference pages under docs/reference/ are generated by node scripts/gen-docs.mjs — regenerate and commit them, never hand-edit. The docs-drift.yml workflow backs this up: it hard-fails a PR when a committed generated reference (e.g. docs/reference/mcp-tools.md) is stale, and posts a non-blocking reminder when code in doc-relevant paths (API endpoints, workflows, blueprints, MCP tools) changes without any docs/** update.

Keep the published documentation tree current. When an implementation plan is complete or replaced, update the current docs to point to the working code and operator skills, then delete the old plan. Git history keeps the plan and its review trail. Do not apply this cleanup rule to decision records or ADRs, release history, legal notices, or active product specs.

When documentation changes introduce, update, invalidate, consolidate, or remove architectural/process visuals, the docs-diagram-audit workflow is a required consideration and step. Run it for repository-wide or cross-page impact; record why a single-diagram docs-diagram-pitch/docs-diagram-iterate pass is sufficient when a full catalog audit is unnecessary. The audit treats repository implementation and current written docs as ground truth, while existing diagrams are legacy artifacts to assess.

Do not hand-edit generated CHANGELOG.md release sections. Add or correct the source changeset instead; the matching GitHub Release notes project that same section (see Releasing). Finally, keep decision records and docs distinct: a .squad/decisions/inbox/ entry captures why a choice was made (an internal audit trail) and never substitutes for updating docs/guide/ / README.md, which tell users how to use the feature.

Questions

Open a GitHub issue or start a discussion — we're happy to help you get oriented.