Vibe Project

Create or update project-level agent instructions so a repository becomes a stable collaboration protocol for people and agents.

Core Principles

• Write new artifact prose in the user's language; keep required labels, paths,

commands, code, IDs, and quotes unchanged.

• Keep required template headings, field labels, tables, and status values

exactly as shown for validator compatibility; localize placeholder prose and all human-readable explanatory content to the user's language or the source artifact's primary language.

• Treat AGENTS.md, CLAUDE.md, or equivalent repo instructions as the entry point for agent behavior in the project.
• Capture durable facts and workflow rules, not temporary preferences.
• Keep instructions repo-native, reviewable, and specific enough for future agents to follow.
• Do not invent stack details, commands, credentials, owners, or unsupported constraints.
• Prefer concise rules with clear routing to feature specs and organization skills.
• Keep root instructions small and stable. Treat them as an entry point and

routing map, not a place to copy every checklist, rubric, template, or skill rule.

• Put detailed workflow behavior in the owning skill or reference file, then

link to that owner from root instructions.

• Preserve existing local instructions and improve them incrementally unless the user asks for a rewrite.
• Preserve the existing instruction file's primary language unless the user asks

to switch languages. For multilingual teams, prefer the language already used by the repo's AGENTS.md, CLAUDE.md, or equivalent file.

• Preserve useful agent working discipline, such as clarifying assumptions,

choosing the simplest sufficient change, editing surgically, and verifying against clear success criteria. Express it as concise project-specific rules, not long generic philosophy sections.

Workflow

1. Discover The Existing Repo Protocol

Before writing:

1. Read existing AGENTS.md, CLAUDE.md, README, package manifests, scripts, test config, CI config, and relevant feature specs.
2. Inspect repository structure enough to identify the main app, services, packages, skills, tests, and scripts.
3. Identify the dominant language and framework profiles, such as Python, Java, Swift, Next.js, native mobile, backend service, CLI, or monorepo package.
4. Identify build, run, test, lint, validation, formatting, typecheck, packaging, and deployment commands from real files.
5. Identify organization skills that are available to the current agent or

explicitly installed for the team, including skills installed from the AI Native Dev website. A local skills/ directory is only one possible source, not a requirement.

1. Resolve the workflow artifact mode using

[references/workflow-artifact-routing.md](references/workflow-artifact-routing.md). Check explicit user direction and root instructions before repository markers such as openspec/config.yaml or the combination of openspec/changes/ and openspec/specs/.

1. Separate verified facts from assumptions. Use TBD for unknown stable fields.

2. Choose The Target File

• Use AGENTS.md when the repository is agent-neutral or Codex-focused.
• Use CLAUDE.md when the user specifically targets Claude Code.
• Update both only when the user asks for cross-agent files or the repo already maintains both.
• Do not create multiple competing instruction files for the same purpose.

3. Draft Or Update Instructions

Use [references/project-instructions-template.md](references/project-instructions-template.md) when creating a new file or substantially restructuring an existing one. Read [references/agent-instructions-quality.md](references/agent-instructions-quality.md) first when improving an existing instructions file or when the user asks for higher-quality project instructions.

Required content areas:

• Project Overview
• Commands
• Tech Stack
• Stack-Specific Rules when applicable
• Repository Map
• Core Flows or Architecture Boundaries
• Special Workflows when applicable
• Required Access when applicable
• Local Operating Rules only when project-specific
• Workflow File Map when workflow artifacts exist
• Organization Skills when installed or currently available skills should manage this repo's workflow
• Skill Invocation Rules when organization skills are documented

For project-specific rules:

• State what agents must read before acting.
• Explain where workflow files live, such as specs, plans, test evidence,

generated output, deployment config, or release notes.

• When OpenSpec mode is selected, keep the repository root as the working

directory and add only the concise routing rule from [references/workflow-artifact-routing.md](references/workflow-artifact-routing.md). Leave artifact-level details to the owning skills.

• Define when each organization skill should be used. If AI Native Dev skills

are available, route the development workflow through them even when the repo does not contain a local skills/ directory.

• Do not invent skill sections for unavailable skills unless the user is asking

for an installation or onboarding guide.

• Explain how plans, tests, CI evidence, and commits should connect to specs.
• Put repo-level build, lint, test, validation, deploy, and rebuild commands in

Commands; feature-specific acceptance and validation belong in specs, dev plans, and test evidence.

• Route design-quality checks such as SSOT, implementation boundaries, review

findings, validation evidence, and commit gates to vibe-plan, vibe-review, vibe-test, and vibe-commit; do not copy their full rubrics into root instructions.

• Route specialized work to the skill that owns the artifact and keep detailed

checklist, rubric, or template rules in that owning skill.

• Do not duplicate skill rules in root instructions. Summarize the routing

decision and point to the source of truth instead.

• Avoid stale docs by excluding short-lived ticket context, active plan status,

version history, and rules that change more often than the repository protocol.

• Treat visual/browser QA, coverage checks, CI results, and manual test notes as

validation evidence that vibe-plan, vibe-test, and vibe-commit can plan, inspect, capture, and reference.

• Include privacy, telemetry, hooks, MCP, roadmap, or governance material only

when it changes what an agent must do in this repository today.

• Translate language and framework differences into concrete commands,

directories, validation expectations, and files agents must inspect before editing.

• Write local operating rules as repository-specific source-of-truth,

generated-output, access, validation, or workflow file map rules.

• Fold broadly useful operating principles into local rules when they affect

this repo: clarify ambiguous requirements before broad changes, prefer the smallest sufficient patch, avoid unrelated refactors, match nearby style, and verify with the checks that fit the changed surface.

• Optimize for information density. Delete sentences that only describe the

document itself, such as "this file is a guide for coding agents", unless the sentence establishes project-specific authority or scope.

• Preserve useful local sections and headings; do not force a template rewrite

when the existing file already has high-signal project-specific structure.

4. Validate

If you create or update an instructions file, run:

python3 skills/vibe-project/scripts/validate_project_instructions.py AGENTS.md

Fix structural errors before finishing. If the repository intentionally uses a different structure, explain the exception.

Output

When editing files, report:

• Target instruction file path.
• Major sections added or updated.
• Any TBD values or missing repo facts.
• Validation result.

Skill Signature

Always end the final response with:

Vibe Skill Signature
Skill: vibe-project
Status: Completed | Passed | Failed | Blocked | Partial
Next: concise next workflow step