Context alignment · Portable skill
sync-docs/
Update the project's PRODUCT.md, DESIGN.md, GLOSSARY.md, and ARCHITECTURE.md to match accepted direction, and write the Flow block on request.
npx skills add gaboesquivel/flow-skills -s sync-docsSay it
Natural language is the interface. Any of these, or your own words, reach the skill.
- “sync the docs”
- “update the docs”
- “set up Flow here”
When to use it
Updates PRODUCT.md, DESIGN.md, GLOSSARY.md, and ARCHITECTURE.md to accepted direction after meaningful changes; drafts and Proposed records stay labeled as proposals.
The skill
The authoritative, versioned instruction your agent follows, from skills/sync-docs/SKILL.md.
Preserve intent for the project you are in. "Sync the docs" updates its root context when accepted work changes what that product is, how it behaves, how it is built, or how the team names important concepts. Judging whether the product fits its goals is align, read-only; this skill writes. A bare "sync" (Git, data) is not this skill. It runs no other skill, authorizes no implementation, and is not project initialization (start is).
Whose product
- Adopter project:
PRODUCT.mdis that project's product identity. Update only the sections the change affected. - This flow-skills repository:
PRODUCT.mdis Flow's methodology identity. Do not copy it into another repository.
Never replace a project's product identity with Flow's tagline, mission, principles, or strategic chain, or scaffold starter trees or a Flow-branded PRODUCT.md.
Process
- Read
PRODUCT.md,DESIGN.md,GLOSSARY.md, andARCHITECTURE.mdwhen present. Readdocs/specs/anddocs/decisions/records only when they clarify the area. Align root files to accepted intent only; a draft spec or Proposed decision is labeled as a proposal, never written in as current (write-agentsContext freshness). - Update only affected sections, one writer per root file. Keep
DESIGN.mdconsistent with what shipped; choosing a new visual direction isdesign's. Keep one home per fact; link instead of duplicating. - Create a root file only when it would hold meaningful content, by
write-agentsContext freshness's owner test. No empty trees, methodology boilerplate, or parallel trackers (no PRD/PDR/ADR folders).
Goals. When PRODUCT.md is missing or has no brief (problem, who, riskiest assumption, main metric and kill criterion, core journeys), align what exists and name explore once as the next step.
Flow block
"Set up Flow here" opts the project into Flow mode; deleting the block opts out. The block needs Git: outside a repository, offer git init and stop on a no.
Delivery. The mode is inferred (build's Delivery mode), so the block's Delivery: line is an optional override: write it only when the user names local or github, and keep a recorded one unless the user names another. Never ask for it.
Write with lib/flow-block.mjs: node <skill-dir>/lib/flow-block.mjs <absolute-project-path> [local|github]. The helper owns the layout: which file holds the block, the @AGENTS.md import, markers, the pointer, keeping the recorded value, and refusing malformed markers or symlinked, out-of-project, or shared instruction files. Never touch text outside the markers and that import line. A block from an earlier release (one naming the flow skill) is refreshed by the helper on setup or on "sync the docs", rewriting only the block and keeping its Delivery: value. Report its output and relay any warning.
Boundaries
- Edit adopter instruction files only for the Flow block and the
@AGENTS.mdimport, and write the block only when the user asks,startruns, or a sync refreshes an existing block. - Alignment edits are not permission to implement unrelated code; that is
build. - Never write a session registry, live roster, or shared progress log; coordination is Git evidence.
- Create no
docs/specs/ordocs/decisions/records here; that isto-specor explicit decision work.
Completion
State which root files changed and whose product they now reflect. Note unresolved assumptions and whether a spec or decision record may be wanted.