AGENTS.md

Agent Operating Guide

Keep stable invariants here; keep implementation detail in scoped docs.

Operating Invariants

• Prioritize task-level goals over local optimizations. Choose execution details autonomously.
• The user communicates in Korean. Respond in Korean for conversation and English for code/docs (unless explicitly requested otherwise).
• Treat cwf:<skill> commands as reserved CWF namespace routes; do not substitute similarly named skills from other plugins.
• If implementation diverges from a pre-designed plan, record the discrepancy in session lessons, report it immediately, and ask for a user decision before proceeding.
• Never delete user-created files without explicit confirmation. Prefer mv over rm.
• For design decisions, surface meaningful alternatives with trade-offs and incorporate user-provided external references before concluding.
• When the user asks for the reason/cause (왜, 원인, 이유, why), answer in explicit 5 Whys structure by default unless the user requests a different format.
• For plugin code or plugin metadata changes, run local plugin-deploy as the default lifecycle workflow.
• Deterministic gates define pass/fail authority; prose must not duplicate or override them.
• Context-deficit resilience is mandatory across skills: after auto-compact/session restart, execution must recover from persisted state/artifacts/handoff files, not implicit conversational memory.
• Missing dependency handling is interactive by default: ask whether to install/configure now, run it on approval, then retry once before fallback.

Before Editing Docs

• Read docs/documentation-guide.md first (principles and scope ownership).
• Read plugins/cwf/skills/refactor/references/docs-criteria.md section 0 before proposing new doc rules.
• For automatable issues, update deterministic gates first (.markdownlint-cli2.jsonc, plugins/cwf/hooks/hooks.json, plugins/cwf/skills/refactor/scripts/check-links.sh, plugins/cwf/skills/refactor/scripts/doc-graph.mjs); keep prose changes for non-automatable policy.

Document Map

Select autonomously what to read or update using the file descriptions in the block below.

Generated by cwf:setup --repo-index --target agents.

Root — Repository-wide orientation and current runtime/session status

• README: Repository overview and install/update entry.
• AGENTS: Cross-runtime invariants and navigation map.
• CLAUDE: Claude runtime adapter and runtime-specific deltas.
• cwf-state: Live workflow state and stage checkpoints (SSOT).
• README.ko: Korean mirror of repository overview.

plugins/cwf/skills — CWF workflow design, execution, and orchestration changes

• setup: Setup workflow and index generation policy.
• update: Version check and update workflow.
• gather: Information acquisition workflow.
• clarify: Requirement clarification workflow.
• plan: Plan drafting workflow.
• review: Multi-review orchestration.
• hitl: Human-in-the-loop diff/chunk review with resumable state.
• impl: Plan-to-implementation orchestration.
• retro: Retrospective workflow.
• handoff: Session and phase handoff synthesis.
• ship: Issue/PR/merge workflow.
• run: End-to-end pipeline orchestration.
• refactor: Multi-mode refactor/docs review workflow.

Skill-internal files are documented in each skill-local README (for example, clarify README).

plugins/cwf/references — Multi-skill concept/protocol consistency

• skill-conventions: Cross-skill convention baseline.
• plan-protocol: Plan quality and structure protocol.
• agent-patterns: Shared multi-agent orchestration patterns.
• context-recovery-protocol: Compact recovery and persistence protocol.
• concept-map: Concept synchronization map across composing skills.
• contract-governance: Contract ownership and lifecycle policy for concept-governed execution.
• expert-advisor-guide: Expert advisor operation model.
• readme-skill-summary-template: Standard skill-summary template for README-level progressive disclosure.

plugins/cwf/hooks — Deterministic runtime hook behavior and gating logic

• hooks manifest: Hook registration manifest.
• cwf-hook-gate: Runtime hook gate and toggle logic.
• hooks script map: Map of hook-local scripts and responsibilities.

plugins/cwf/scripts — CWF operational scripts used by setup/session flows

• scripts map: Map of operational scripts under plugins/cwf/scripts.

scripts — Deterministic automation, verification, and maintenance operations

Runtime behavior belongs in plugins/cwf/hooks; repository operations belong in scripts.

• check-schemas: JSON schema validation for tracked CWF config/manifests.
• doc-churn: Documentation churn/staleness reporting from git history.
• find-duplicates: Near-duplicate markdown block detection.

docs — Project standards, architectural decisions, and documentation policy

• project-context: Project/org facts and long-lived conventions.
• architecture-patterns: Implementation and integration patterns.
• cwf-artifact-migration-plan: Stage-based .cwf artifact migration roadmap.
• documentation-guide: Documentation quality principles and scope rules.
• plugin-dev-cheatsheet: Practical development/testing/deploy workflows.
• interactive-doc-review-protocol: Interactive documentation review process and chunking strategy.

references — External conceptual frameworks used by this repository

• anthropic-skills-guide/README: Anthropic skills guide index.
• essence-of-software/distillation: Core concept distillation used by review and design docs.
• sw-factory/analysis: Analysis report on software-factory patterns and the agentic development model.