name: ai-cowork-process description: Defines the standard AI cowork process for repository documentation, synchronization, scope discipline, and versioning metadata without introducing technology-specific coding or architecture rules.

AI Cowork Process

Purpose

This skill defines the standard collaboration process between a human developer and an AI agent when working on software repositories.

Its purpose is to keep the repository understandable for humans while also maintaining the deeper project knowledge an AI needs to work safely and consistently.

This skill focuses on:

• repository documentation structure,
• separation of human-readable documentation and AI-maintained project knowledge,
• synchronization between both representations,
• scope discipline,
• documentation maintenance,
• API documentation handling,
• versioning-related commit classification,
• and protection of generated version history.

This skill deliberately does not define:

• programming-language coding rules,
• framework selection,
• technology-specific architecture guidelines,
• naming conventions for source code,
• testing frameworks,
• deployment architecture,
• security standards,
• or other technology-specific implementation standards.

Those concerns belong in separate dedicated skills.

1. Standard repository documentation structure

Repositories following this process should use the following human-readable documentation structure:

/
├── README.md
├── doc/
│   ├── 1-requirements.md
│   ├── 2-architecture.md
│   ├── 3-quickstart.md
│   ├── api.*                 # optional, only when explicitly chosen
│   ├── changelog.md
│   └── ideas.md
└── .agents/
    └── skills/
        └── most-important-details-for-<project-name>/
            └── SKILL.md

The exact source-code structure of the repository is outside the scope of this skill.

1.1 File naming and reading order

The core documentation files in doc/ carry a numeric prefix that defines their fixed reading order:

1. 1-requirements.md – what the project should do and why
2. 2-architecture.md – how the system is structured
3. 3-quickstart.md – how to get started and use it

All other documentation files (changelog.md, ideas.md, optional API documentation) intentionally have no numeric prefix. Because numbered files sort first, these unnumbered files automatically appear after the core documents in file listings.

Rules:

• Use exactly these file names; do not create unnumbered duplicates such as doc/requirements.md.
• If a repository still uses the unnumbered legacy names, rename them to the numbered names and update all links (README, other documents, project AI skill) in the same change.
• Do not assign numbers to additional documents on your own. Extending the numbered sequence requires an explicit developer decision.

1.2 Documentation language

README.md and all documentation files in doc/ MUST be written in English.

This applies regardless of the language used in the conversation with the developer, in issues, or in requirement descriptions. When input is provided in another language, translate its content into English when writing it to the documentation.

If existing documentation is written in another language, translate it into English when it is next substantially edited, or when the developer asks for it.

2. Two synchronized representations of the project

Each repository has two complementary representations of project knowledge.

2.1 Human-readable project documentation

Human-readable project knowledge is maintained primarily in:

• README.md
• doc/1-requirements.md
• doc/2-architecture.md
• doc/3-quickstart.md
• doc/ideas.md
• optional explicitly maintained API documentation

These files are intended for developers, users, maintainers, reviewers, and other humans.

They should remain structured, concise, understandable, and useful without requiring AI assistance.

2.2 AI-maintained project knowledge

Detailed project-specific AI knowledge is maintained in:

.agents/skills/most-important-details-for-<project-name>/SKILL.md

This project skill may contain deeper implementation knowledge that would be too detailed or distracting for normal human-readable project documentation.

Examples include:

• implementation-specific relationships,
• non-obvious internal behavior,
• important technical constraints,
• known pitfalls,
• relevant historical implementation decisions,
• internal conventions specific to the project,
• subtle dependencies between components,
• details required to safely modify the repository.

The project AI skill is the detailed operational memory for AI-assisted development.

3. Authority and synchronization

Human-readable documentation and the project AI skill MUST be kept synchronized.

They do not serve exactly the same purpose and therefore do not need to contain the same level of detail.

The guiding principle is:

Human-readable documentation defines what the project is, what it should do, how it is used, and its relevant high-level architecture.
The project AI skill maintains the additional detailed knowledge required for safe and consistent AI-assisted development.

Where both representations overlap:

• human-readable documentation is authoritative for product intent,
• human-readable documentation is authoritative for externally visible behavior,
• human-readable documentation is authoritative for documented user workflows,
• the project AI skill may add deeper technical details,
• the project AI skill MUST NOT silently contradict human-readable project documentation.

If the implementation, documentation, and AI project knowledge disagree materially, the contradiction must be identified and resolved rather than silently normalized.

4. doc/1-requirements.md

doc/1-requirements.md is the leading human-readable source for project intent and active requirements.

It should contain, where relevant:

• project goals,
• target audiences,
• user needs,
• wishes,
• epics,
• functional requirements,
• non-functional requirements,
• use cases,
• constraints,
• boundaries,
• important exclusions and non-goals,
• externally observable expected behavior.

The document should remain easy for humans to read.

Do not transform it into an unnecessarily formal or machine-oriented specification unless explicitly requested.

Avoid excessive identifiers, metadata blocks, or specification boilerplate when normal headings, concise paragraphs, lists, and examples are sufficient.

When a developer request changes intended project behavior, doc/1-requirements.md should be updated accordingly.

5. doc/2-architecture.md

doc/2-architecture.md describes the human-relevant structure of the system.

Its purpose is to answer:

• How is the system fundamentally structured?
• What are the major components?
• How do the important parts interact?
• What are the major data flows?
• Which external systems are relevant?
• Which architectural boundaries matter?
• Which major architectural decisions are important for understanding the system?

It should remain high-level enough to be useful to humans.

Do not move every implementation detail into this document.

Detailed knowledge that is primarily useful for AI-assisted maintenance belongs in the project-specific most-important-details-for-<project-name> skill.

Example distinction:

A statement such as:

A filesystem cache sits between the external provider and the rendering layer to decouple runtime behavior from external API availability.

belongs in doc/2-architecture.md.

A statement such as:

Method X must pass parameter Y when calling component Z because an otherwise valid fallback path triggers a provider-specific edge case.

usually belongs in the project AI skill.

6. doc/3-quickstart.md

doc/3-quickstart.md contains practical step-by-step documentation for important use cases.

Typical content includes:

• installation,
• setup,
• configuration,
• first successful execution,
• common workflows,
• concrete examples,
• commands,
• expected results,
• relevant troubleshooting,
• practical integration examples.

Structure this document primarily around what users or developers want to accomplish.

Do not organize it merely by internal source-code layout.

When a change affects a documented workflow, update the relevant quickstart section as part of the same change.

7. doc/ideas.md

doc/ideas.md stores future concepts that are intentionally not yet active requirements.

Examples include:

• possible future features,
• strategic directions,
• future integrations,
• architectural possibilities,
• experiments,
• optimization ideas,
• UX improvements,
• larger refactoring concepts.

Content in doc/ideas.md MUST NOT automatically be implemented.

An idea becomes an implementation requirement only after explicit developer commitment.

When an idea is accepted for implementation:

1. integrate the resulting requirement into doc/1-requirements.md,
2. implement it,
3. update affected documentation,
4. update or remove the corresponding idea when appropriate.

This separation allows future thinking without silently expanding current scope.

8. doc/changelog.md

doc/changelog.md is the standard human-readable version history for the repository.

It is intentionally stored inside doc/ because it should be easily consumable by humans.

However, it is maintained by the versioning/build pipeline.

The AI MUST NOT manually maintain doc/changelog.md.

The AI may:

• read it,
• use it for historical context,
• reference it,
• verify that it exists where expected.

The AI MUST NOT:

• manually add release entries,
• rewrite previous release history,
• manually create normal release notes inside it,
• use it as a substitute for correct versioning metadata.

Treat doc/changelog.md as a generated or pipeline-maintained artifact.

9. README.md

The root README.md is the concise entry point into the repository.

Use the following outline as the default structure:

# <Project name>

## About
## Motivation
## Examples
## Differentiation
## Documentation

The headings above are the recommended default headings. The explanations below describe the intended content of each section; do not copy them into the README as text. Omit a section when it adds no value for the specific project (e.g. Differentiation when there is no relevant alternative).

About

A short, concrete explanation of what the project is and does – typically one or two paragraphs.

Motivation

Why the project exists and which problem it solves.

Examples

A few concise use-case examples that quickly demonstrate the value and typical usage of the project.

They should encourage further exploration rather than duplicate the complete quickstart.

Differentiation

A concise and factual explanation of important differences from known competing or alternative implementations, where this is relevant.

Documentation

The README MUST provide relative links to the relevant human-readable documentation, in the fixed order defined in section 1.1.

At minimum, where the corresponding files exist:

- [Requirements](doc/1-requirements.md)
- [Architecture](doc/2-architecture.md)
- [Quickstart](doc/3-quickstart.md)
- [Changelog](doc/changelog.md)
- [Ideas and future directions](doc/ideas.md)

If repository-maintained API documentation exists, link it as well.

All repository-internal documentation links MUST be relative.

Do not use machine-specific absolute paths, local drive paths, repository-host-specific absolute URLs, or environment-specific locations when a relative repository link is sufficient.

The goal is that the documentation remains navigable regardless of where the repository is cloned, mounted, browsed, archived, or rendered.

10. Optional API documentation

API documentation is optional and MUST NOT be created automatically merely because a project exposes an API.

For services that can generate their API contract from the implementation or running application, prefer generated documentation such as OpenAPI or Swagger.

Generated API descriptions are generally preferred because they are less likely to drift away from the actual implementation.

The default assumption is therefore:

• generate technical API contracts where practical,
• avoid redundant static API definitions,
• do not create manually maintained API documentation without an explicit reason.

10.1 Explicit opt-in

Repository-maintained API documentation may be added when the developer explicitly requests and commits to maintaining it.

Examples include:

• doc/api.md,
• OpenAPI definitions,
• Swagger definitions,
• concrete request/response examples,
• integration guides,
• service-call examples.

Before introducing repository-maintained API documentation, obtain explicit developer commitment.

10.2 Synchronization responsibility

Once repository-maintained API documentation exists, it becomes part of the active documentation set.

The AI MUST then keep it synchronized with relevant implementation changes.

Do not knowingly leave repository API documentation inconsistent with actual behavior.

Where generated and human-readable API documentation both exist:

• generated contracts describe the current technical interface,
• human-readable API documentation should focus on usage, examples, integration guidance, constraints, and context,
• avoid unnecessary duplication of generated schemas.

11. Documentation synchronization workflow

Whenever a repository change is made, determine which project representations are affected.

Review at least:

• doc/1-requirements.md
• doc/2-architecture.md
• doc/3-quickstart.md
• doc/ideas.md
• optional repository-maintained API documentation
• the project-specific most-important-details-for-<project-name> skill
• README.md

Do not update every document mechanically.

Update only the documents whose meaning is affected.

The goal is semantic synchronization, not redundant duplication.

Examples:

• changed product behavior → usually update 1-requirements.md
• changed user workflow → usually update 3-quickstart.md
• changed major system structure → usually update 2-architecture.md
• newly discovered future concept → consider ideas.md
• changed subtle implementation constraint → update the project AI skill
• changed public API with opted-in repository API docs → update those docs
• added or removed documentation files → update README links

12. Scope discipline

During development, distinguish between three categories.

Required now

Work necessary to satisfy an active requirement.

Implement it.

Necessary technical work

Refactoring, tests, migrations, infrastructure changes, or internal modifications genuinely required to implement the requested behavior safely.

Implement when appropriate.

Future improvement

Useful work that is not necessary for the current requirement.

Do not silently implement it.

Instead:

• add it to doc/ideas.md when appropriate,
• or discuss it with the developer.

Do not use AI autonomy as justification for expanding product scope.

13. Versioning responsibility

The AI does not directly manage repository versions.

Versioning is performed by the repository's build/release pipeline and the configured versioning tooling.

The AI's responsibility is to provide the semantic classification required by that process through commit messages.

The pipeline is responsible for deriving the actual version and maintaining generated version artifacts such as doc/changelog.md.

14. Commit-message versioning triggers

Use the following exact prefixes when applicable.

Breaking changes

For changes requiring a semantic-versioning major increment:

breaking change: <description>

Example:

breaking change: replace legacy provider configuration schema

New features

For meaningful backward-compatible functionality requiring a semantic-versioning minor increment:

new feature: <description>

Example:

new feature: add multi-repository provider support

Other changes

Bug fixes, refactorings, documentation updates, tests, maintenance work, and other changes that are neither breaking changes nor meaningful new functionality must NOT use these trigger prefixes merely because code changed.

Use a normal descriptive commit message.

If a change is both a new feature and a breaking change, classify it as a breaking change.

Documentation-only and skill-only changes

If a commit touches only AI skills (.agents/skills/**) and/or human-readable documentation (doc/**, root README.md), and nothing else, the commit message MUST end with:

[skip ci]

Example:

docs: clarify quickstart configuration steps [skip ci]

Such commits never use the breaking change: or new feature: triggers.

As soon as any other file is part of the commit (source code, project files, build or pipeline configuration, packages, …), do NOT add [skip ci]. Classify the commit as described in section 15 instead.

15. Versioning classification

Before proposing or creating a commit message, classify the change:

Does this break an existing public contract,
configuration, API, supported workflow,
or externally relied-upon behavior?
        │
       YES
        ↓
breaking change: ...

        NO
        │
        ▼
Does this add meaningful backward-compatible
functionality?
        │
       YES
        ↓
new feature: ...

        NO
        │
        ▼
normal descriptive commit message

Do not manually edit doc/changelog.md as a substitute for this classification.

16. Definition of done

A repository change is complete when, where applicable:

• active requirements are satisfied,
• the implementation is coherent,
• human-readable documentation remains accurate,
• the project-specific AI skill remains accurate,
• both knowledge representations are synchronized,
• README documentation links remain complete, relative, and in the fixed order,
• README.md and all files in doc/ are written in English,
• the core documentation files use their numbered names (1-requirements.md, 2-architecture.md, 3-quickstart.md),
• relevant API documentation is synchronized if it was explicitly opted in,
• future ideas were not accidentally promoted into requirements,
• doc/changelog.md was not manually maintained,
• versioning impact was correctly classified,
• the appropriate commit-message trigger was used where required,
• commits containing only skill and/or documentation changes end with [skip ci].

17. Maintenance boundary of this skill

This skill itself MUST remain narrowly focused on the AI cowork process for repository documentation, synchronization, scope discipline, and versioning metadata.

When maintaining this skill, do NOT expand it into unrelated domains.

In particular, do not add:

• C# coding rules,
• .NET architecture rules,
• WordPress coding conventions,
• framework-selection policies,
• source-code naming rules,
• UI standards,
• testing-framework guidance,
• deployment standards,
• infrastructure rules,
• security standards,
• domain-specific application logic.

Such concerns belong in separate dedicated skills.

If a new rule does not directly concern:

• repository documentation structure,
• synchronization between human-readable documentation and AI project knowledge,
• documentation maintenance,
• scope handling,
• API-documentation maintenance,
• or versioning metadata,

it should normally be placed in another skill instead of extending this one.

The goal is to keep this skill stable, reusable across repositories, and maintainable from one central location.