Project bootstrap

Use as supporting infrastructure for orientation and documentation setup; users do not need to remember to bootstrap before ordinary work. Read-only orientation does not authorize setup edits. Installation alone does not make a repository adopt YMAS document families. Instructions below to record or establish governance apply only during authorized setup.

Use evaluate-repository for a standalone read-only assessment of documentation and YMAS fit, and documentation-consolidation for an explicit migration of existing documentation. For an implementation, audit, or bug task, gather only the foundation needed and return to that task's workflow.

1. Read repository AGENTS.md or its established equivalent. Locate its documentation standard or equivalent; if none exists, discover the actual conventions before proposing any structure.
2. Identify the project's explicit authority hierarchy and the documents relevant to this task: current product truth, architecture, specifications, accepted decisions, and current operational context. Report gaps or conflicts rather than inventing authority.
3. Inspect the applicable operational families for their highest sequence numbers across Level 2 categories, including archived and legacy locations. Distinguish current records from archives. Load only material needed for the task.
4. Before creating documentation, search for an existing owner to update. Follow its documentation standard and document versioning: sequence numbers identify documents, not revisions. Keep a newer revision in the existing current folder and stable filename, retain its ID, record the newer revision as dotted metadata, and archive the complete predecessor before replacement. Derive the archive suffix from that predecessor: an old Version: v3.1 uses _v3dot1.md. Preserve historical links; never restart a family sequence because of a category or directory change. Apply setup changes only within authorized adoption scope.
5. Before code changes, inspect affected implementation and tests. Inspect Git history when existing behavior has a non-obvious purpose. Record material historical constraints as evidence, not authority.

When the repository has adopted YMAS documentation conventions, use its own standard for family names, paths, authority, and Level 2 taxonomy. Determine whether a taxonomy already exists; inspect established durable systems and domains, current and legacy categories, and canonical tokens. Record the adopted vocabulary or selection rules in that project's documentation standard. Level 2 primarily enables retrieval across document families: reuse one canonical token per concept so a search for _<L2_CATEGORY>_ finds that area's records. Avoid synonyms, plural or spelling variants, unnecessary abbreviations, and overlapping categories unless the project explicitly defines separate concepts. Add a category only for a durable distinction. Do not invent one when ownership is unresolved; follow a documented fallback or mark classification unresolved. For a new YMAS project, a minimal proposed taxonomy remains provisional until adopted. Do not impose YMAS naming or taxonomy on an unrelated repository.

By default, new numbered files use <FAMILY>_<L2_CATEGORY>_<ID>_<l3-description>.md, with a single uppercase Level 2 token, underscores between structural segments, and lowercase hyphen-separated words in the final description. Each family has one independent three-digit sequence across all categories unless the adopting repository's current authority explicitly establishes another rule. Never use roadmap, milestone, phase, sprint, release, campaign, or other temporary planning labels as Level 2 categories. Preserve existing IDs and valid legacy filenames; search current, archived, and legacy locations before allocating the next family ID.

OPS_NEXT is the sole ordering exception: create OPS_NEXT_<next-family-id>_<canonical-L2>_<description>.md, for example OPS_NEXT_005_DOCS_update-installation-guidance.md. It prioritizes chronological/current-action retrieval; other families prioritize domain retrieval. Both retain Level 2. Find the highest numeric OPS_NEXT ID across categories and legacy locations during migrations; do not infer recency from alphabetical Level 2 grouping. Unless project authority explicitly says otherwise, that highest ID is the current recommended next action. Never restart its family-wide sequence when categories change, reuse IDs, or renumber records. Do not normalize the sequence-first pattern back to the default ordering.

The common families are SOT, RM, SYS, SPEC, SPECARC, PLAN, AUDIT, ADR, BUG, OPS_TASK, OPS_STATE, OPS_NEXT, OPS_DECISION, OPS_SPECDEF, OPS_WORKFLOW, and REF. Adopt only those the project needs.

For an explicitly YMAS project that needs a new documentation standard, adapt the standard template to that repository's actual authority and directories. Preserve any existing project rules. Add a short pointer to the standard in the repository instruction file. Do not copy the template unchanged when its authority fields are unresolved.

When a repository explicitly adopts the YMAS workflow system, establish concise defaults in its own agent instructions (or equivalent) that route through this package's INDEX.md, apply the agent execution loop automatically to substantive work, and require isolated workbranches for repository writes. Use actual installed paths and adapt to the repository's existing routing and Git process. Where same-name contracts differ, record the intended qualified package/contract and version; inspect available provenance, surface unresolved material ambiguity, and preserve personal skills. Roles express responsibilities; model/effort preferences are configurable repository/task choices, never universal vendor mandates. Preserve equivalent or stronger rules; do not overwrite existing agent or Git governance. Surface conflicts and follow the repository's governing authority.

For substantive product or system work, make spec-driven-development and its workflow discoverable through the adopting repository's established routing. Map its layers to existing authority; add only layers the work needs. Do not turn routine or already specified tasks into mandatory document creation.

During authorized YMAS adoption, establish the no-code-comments rule through a concise local agent-instruction pointer and identify the project's specification owners for explanations and reasoning. Preserve governing authority and surface any conflicting notice, directive or documentation requirement instead of silently adding an exception. Read-only orientation or installation alone does not authorize this policy change.

For specification formalization, preserve the order: discussion → provisional True Spec worksheet when useful → accepted decisions → sibling SPEC and/or SPECARC in either design order → integrated systems.md derived from the complete current specification set when enough material exists for a useful map. An existing map supplies architecture/impact context, not new requirements or authority to override newly settled decisions. After substantive SPEC or SPECARC creation/revision, review the complete set and update it when architecture, ownership, boundaries, dependencies, interfaces, flows, or cross-system behavior change. Retain SYS and ADR roles rather than treating them as SPECARC synonyms. Preserve its canonical path and version/archive it like other project documents.

Use workflow-orientation for a user asking how to begin; it explains the process without executing it. Use true-spec-worksheet for unresolved consequential product or architecture choices before formalization. Existing projects resume from established authority and current state rather than restarting discovery.

End with a concise map of governing sources, current context, unresolved authority questions, and the files changed, if any.

Use human explanation and editorial judgment for readable explanations and documentation. Consider ordinary documentation purposes only where useful; do not reclassify canonical specifications or infer migration authority from editorial guidance.