Skip to content

docs: strengthen docs system and release guidance #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
vaur94 merged 5 commits into from
Mar 9, 2026
Merged

docs: strengthen docs system and release guidance #6

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
dcf9f80
docs(readme): strengthen bilingual navigation and status
vaur94 Mar 9, 2026
f52295d
docs(usage): expand usage and release guidance
vaur94 Mar 9, 2026
8af7f75
docs(guides): add governance and recommendation guides
vaur94 Mar 9, 2026
c599976
docs(policy): clarify repository support and conduct
vaur94 Mar 9, 2026
aadc90c
docs(metadata): align package metadata and changelog
vaur94 Mar 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog:
https://keepachangelog.com/en/1.1.0/

## [Unreleased]

### Docs

- Strengthened the bilingual documentation system with direct links, release guidance, governance guidance, and clearer usage flows.
- Clarified that npm publication and the first GitHub release have not happened yet.

## [0.1.0] - 2026-03-09
Comment on lines +8 to 15
Copy link

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The CHANGELOG has [0.1.0] - 2026-03-09 as a formal dated release entry (following Keep a Changelog conventions, where a dated entry typically indicates a published release), but the new [Unreleased] section immediately above it, along with multiple documentation files, explicitly states that npm publication has not happened yet. In Keep a Changelog format, a dated version entry implies it has been released. If 0.1.0 has not been published to npm, the [0.1.0] - 2026-03-09 entry should either remain as [Unreleased] or its date should be removed to avoid confusion.

Copilot uses AI. Check for mistakes.

### Added
Expand Down
6 changes: 5 additions & 1 deletion CODE_OF_CONDUCT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,11 @@ Project maintainers are responsible for clarifying and enforcing this Code of Co

## Reporting

If you experience or witness unacceptable behavior, report it to the maintainers through GitHub using a private channel whenever possible. Public issue threads should not be used for sensitive reports.
If you experience or witness unacceptable behavior:

1. do not use public issue threads for sensitive reports
2. contact the maintainer privately through GitHub
3. if the report overlaps with a security issue, follow `SECURITY.md` instead

## Scope

Expand Down
13 changes: 10 additions & 3 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,12 @@

Thanks for contributing.

## Repository Reality

- CI and protected-branch automation are active.
- npm release automation is configured but the first public release has not happened yet.
- Documentation is maintained in both English and Turkish for user-facing topics.

## Local Setup

1. Install Bun.
Expand Down Expand Up @@ -54,6 +60,7 @@ The repository includes a GitHub release workflow for npm publishing.

## Further Reading

- `docs/README.md`
- `docs/en/usage-guide.md`
- `docs/en/model-recommendations.md`
- [Documentation Hub](./docs/README.md)
- [Usage Guide](./docs/en/usage-guide.md)
- [Pull Request Guide](./docs/en/pull-request-guide.md)
- [Release Guide](./docs/en/release-guide.md)
211 changes: 109 additions & 102 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,43 +4,86 @@
[![Release](https://github.com/vaur94/opencode-ceo/actions/workflows/release.yml/badge.svg)](https://github.com/vaur94/opencode-ceo/actions/workflows/release.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

Transform OpenCode into a deterministic software company OS.
Build a disciplined, delivery-aware OpenCode workflow with a CEO agent, specialist delegation, persistent state, and GitHub handoff.

`opencode-ceo` is an OpenCode plugin that runs software work through a controlled delivery pipeline. The CEO agent decomposes work, delegates to specialists, enforces gates, persists artifacts/state, and can deliver changes into GitHub with branch and pull request automation.
## 🚀 What This Project Does

## Language
`opencode-ceo` is an OpenCode plugin that turns software work into a controlled delivery pipeline. Instead of letting one agent improvise the whole task, it moves work through defined stages, persists decisions and artifacts, and can prepare Git branches and pull requests when the repository is ready.

- English: `README.md`
- Turkish: `README.tr.md`
## 🌍 Language Options

## Why opencode-ceo?
- [English README](./README.md)
- [Turkce README](./README.tr.md)

- Deterministic pipeline ownership instead of ad-hoc agent output.
- SQLite-backed state and artifact persistence for long-running work.
- Delivery-aware GitHub tooling for branches, PRs, and repository fingerprinting.
- Gated autonomy levels for teams that want review points before delivery.
## ⚡ Status At A Glance

## Documentation Map
- CI on `main`: enabled and protected
- Release workflow: configured in `.github/workflows/release.yml`
- Dependabot: configured in `.github/dependabot.yml`
- npm package publication: not published yet
- GitHub release: not created yet

| Topic | English | Turkish |
|------|---------|---------|
| Documentation hub | `docs/README.md` | `docs/README.md` |
| Usage guide | `docs/en/usage-guide.md` | `docs/tr/kullanim-kilavuzu.md` |
| PR guide | `docs/en/pull-request-guide.md` | `docs/tr/pr-kilavuzu.md` |
| Model recommendations | `docs/en/model-recommendations.md` | `docs/tr/model-onerileri.md` |
| Architecture | `docs/ARCHITECTURE.md` | `docs/ARCHITECTURE.md` |
| Contributing | `CONTRIBUTING.md` | `CONTRIBUTING.md` |
| Security | `SECURITY.md` | `SECURITY.md` |
| Support | `SUPPORT.md` | `SUPPORT.md` |
| Changelog | `CHANGELOG.md` | `CHANGELOG.md` |
If you are evaluating release readiness, start with the [Release Guide](./docs/en/release-guide.md).

## Installation
## ✨ Why opencode-ceo?

- Deterministic pipeline ownership instead of one-shot agent output
- SQLite-backed artifacts, gates, and state for long-running sessions
- GitHub-aware delivery helpers for branch and PR preparation
- Configurable autonomy for teams that want review gates before delivery

## 🧭 Documentation Hub

Start here if you want the full docs map:

- [Documentation Hub](./docs/README.md)

### Table of Contents

- [What This Project Does](#-what-this-project-does)
- [Status At A Glance](#-status-at-a-glance)
- [Documentation Hub](#-documentation-hub)
- [Installation Status](#-installation-status)
- [Configuration Example](#️-configuration-example)
- [Pipeline Overview](#️-pipeline-overview)
- [GitHub Delivery](#-github-delivery)
- [Local Verification](#-local-verification)
- [Repository Controls](#️-repository-controls)

Core guides:

- [Usage Guide](./docs/en/usage-guide.md)
- [Pull Request Guide](./docs/en/pull-request-guide.md)
- [Model Recommendations](./docs/en/model-recommendations.md)
- [Release Guide](./docs/en/release-guide.md)
- [Governance and Branch Policy](./docs/en/governance-guide.md)
- [Architecture](./docs/ARCHITECTURE.md)

Repository policies:

- [Contributing](./CONTRIBUTING.md)
- [Security](./SECURITY.md)
- [Support](./SUPPORT.md)
- [Code of Conduct](./CODE_OF_CONDUCT.md)
- [Changelog](./CHANGELOG.md)
- [License](./LICENSE)

## 📦 Installation Status

The package name is `opencode-ceo`, but the first public npm release has not been published yet.

Current options:

- local development from this repository
- future npm install after the first release

Planned install command after publication:

```bash
npm install opencode-ceo
```

Add the plugin to your `opencode.json` configuration:
## ⚙️ Configuration Example

```json
{
Expand All @@ -60,9 +103,7 @@ Add the plugin to your `opencode.json` configuration:
}
```

## Quick Start

The smallest setup uses full autonomy:
Minimal full-autonomy setup:

```json
{
Expand All @@ -77,84 +118,45 @@ The smallest setup uses full autonomy:
}
```

Once configured, the `ceo` agent owns the task, delegates to hidden specialists, and advances the pipeline until work is blocked, failed, or completed.
## 🏗️ Pipeline Overview

## GitHub Delivery
```text
[intake] -> [decompose] -> [implement] -> [review] -> [test] -> [deliver] -> [completed]
\-> [blocked] \-> [failed]
```

`opencode-ceo` includes a GitHub-aware delivery path:
Stage summary:

- `ceo_branch_prepare` creates `ceo/<pipeline-id>/<slug>` branches.
- `ceo_pr_prepare` pushes the active branch to `origin` and opens a PR with `gh pr create`.
- `ceo_repo_fingerprint` reports git state, remote information, and repository readiness.
- `intake`: capture the task and detect the project stack
- `decompose`: build an implementation plan
- `implement`: produce the change set
- `review`: inspect correctness and risk
- `test`: validate behavior and regression safety
- `deliver`: prepare branch and PR output

Authenticate GitHub CLI before using the PR automation path:
For deeper detail, see [Architecture](./docs/ARCHITECTURE.md).

```bash
gh auth login
```
## 🧠 Model Preferences

## Configuration
You can tune `modelPreferences` by stage. Suggested defaults and trade-offs live here:

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `autonomyLevel` | `full` \| `gated` \| `manual` | `full` | Controls how much human intervention is required for pipeline transitions. |
| `gates` | `Record<string, "auto" \| "manual">` | `{}` | Configures specific approval gates such as `approve-plan` or `approve-delivery`. |
| `disabledAgents` | `string[]` | `[]` | Disables selected specialist agents. |
| `modelPreferences` | `Object` | `{}` | Overrides preferred models for stages such as implement, review, and test. |
- [Model Recommendations](./docs/en/model-recommendations.md)

For practical model suggestions, see `docs/en/model-recommendations.md`.
## 🔀 GitHub Delivery

## Agents
`opencode-ceo` includes GitHub-aware delivery tools:

The plugin provides one primary CEO agent and seven hidden specialists.
- `ceo_branch_prepare` creates `ceo/<pipeline-id>/<slug>` branches
- `ceo_pr_prepare` pushes the active branch to `origin` and opens a PR with `gh pr create`
- `ceo_repo_fingerprint` reports remote, git status, and general repo readiness

| Agent ID | Purpose | Hidden |
|----------|---------|--------|
| `ceo` | Owns the delivery pipeline and delegates work. | No |
| `ceo-architect` | Breaks complex work into implementation-ready plans. | Yes |
| `ceo-implementer` | Implements scoped code changes and validates them locally. | Yes |
| `ceo-reviewer` | Reviews code changes for correctness and risk. | Yes |
| `ceo-tester` | Runs focused validation and safety checks. | Yes |
| `ceo-ts-specialist` | Handles TypeScript-heavy implementation and type issues. | Yes |
| `ceo-python-specialist` | Handles Python-specific implementation and runtime issues. | Yes |
| `ceo-go-specialist` | Handles Go-specific implementation and tooling issues. | Yes |
Before using PR automation locally:

## Pipeline Stages

```text
[intake] -> [decompose] -> [implement] -> [review] -> [test] -> [deliver] -> [completed]
\-> [blocked] \-> [failed]
```bash
gh auth login
```

| Stage | Description | Primary Agent |
|-------|-------------|---------------|
| **Intake** | Initial task analysis and feasibility check. | `ceo` |
| **Decompose** | Breaking the task into a concrete implementation plan. | `ceo-architect` |
| **Implement** | Writing code and performing local verification. | `ceo-implementer` |
| **Review** | Peer review of changes for quality and standards. | `ceo-reviewer` |
| **Test** | Rigorous verification using test suites and CI-like checks. | `ceo-tester` |
| **Deliver** | Final packaging and submission. | `ceo` |

## Tool List

| Tool | Purpose |
|------|---------|
| `ceo_delegate` | Delegate work to a hidden subagent with explicit tool restrictions. |
| `ceo_stage_transition` | Move the pipeline through valid FSM states. |
| `ceo_gate_run` | Run an approval gate and optionally request manual approval. |
| `ceo_gate_status` | Inspect gate state for a pipeline. |
| `ceo_artifact_write` | Persist stage artifacts in SQLite-backed storage. |
| `ceo_artifact_read` | Read persisted artifacts. |
| `ceo_decision_log` | Record decisions in the audit trail. |
| `ceo_branch_prepare` | Create a delivery branch. |
| `ceo_pr_prepare` | Create a PR and persist its URL artifact. |
| `ceo_repo_fingerprint` | Return repository metadata, remote info, and git status. |
| `ceo_stack_detect` | Detect the active project stack. |
| `ceo_delivery_format` | Produce a markdown delivery summary. |
| `ceo_context_pack` | Pack SQLite-backed state for compaction. |
| `ceo_context_restore` | Restore packed state after compaction or resume. |

## Development
## 🧪 Local Verification

```bash
bun install
Expand All @@ -168,20 +170,25 @@ Useful individual commands:
- `bun test`
- `bun run pack:check`

## Repository Standards
## 🛡️ Repository Controls

- protected `main` branch
- required `quality`, `tests`, and `package` checks
- linear history enforced
- force-push disabled on `main`
- conversations must be resolved before merge
- Dependabot active for npm and GitHub Actions
- CI currently listens to both `main` and `master` for compatibility, while `main` is the active branch policy target

- CI is enforced on `main` with separate quality, test, and package checks.
- Release publishing runs from tags through `.github/workflows/release.yml`.
- Dependabot is configured for npm and GitHub Actions updates.
- Branch protection requires reviews and passing checks before merge.
Details: [Governance and Branch Policy](./docs/en/governance-guide.md)

## Next Docs
## 📚 Next Steps

- Getting started and operations: `docs/en/usage-guide.md`
- Pull request process: `docs/en/pull-request-guide.md`
- Model tuning by stage: `docs/en/model-recommendations.md`
- Architecture details: `docs/ARCHITECTURE.md`
- operational setup: [Usage Guide](./docs/en/usage-guide.md)
- contribution flow: [Pull Request Guide](./docs/en/pull-request-guide.md)
- release flow: [Release Guide](./docs/en/release-guide.md)
- repo policy: [Governance and Branch Policy](./docs/en/governance-guide.md)

## License
## 📄 License

MIT
Loading