Skip to content

Commit 7fc12e9

Browse files
PEDZEOPEDZEO
committed
Add CI and English documentation
1 parent 57d06ba commit 7fc12e9

4 files changed

Lines changed: 290 additions & 0 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: ["main"]
6+
pull_request:
7+
8+
jobs:
9+
smoke:
10+
name: Smoke (${{ matrix.os }})
11+
runs-on: ${{ matrix.os }}
12+
strategy:
13+
fail-fast: false
14+
matrix:
15+
os: [ubuntu-latest, windows-latest]
16+
17+
steps:
18+
- name: Checkout
19+
uses: actions/checkout@v4
20+
21+
- name: Setup Python
22+
uses: actions/setup-python@v5
23+
with:
24+
python-version: "3.11"
25+
26+
- name: Show Python version
27+
run: python --version
28+
29+
- name: Validate workflow templates
30+
run: python tools/validate_workflow.py --memory-dir memory
31+
32+
- name: Scaffold task
33+
run: >
34+
python tools/scaffold_task.py
35+
--memory-dir memory
36+
--goal "CI smoke check"
37+
--done-criteria "Smoke commands complete successfully"
38+
--scope "tools/, memory/"
39+
--tests "python tools/validate_workflow.py --memory-dir memory"
40+
--next-step "Run the remaining CLI commands"
41+
--delegate "none"
42+
43+
- name: Create handoff
44+
run: >
45+
python tools/create_handoff.py
46+
--memory-dir memory
47+
--role reviewer
48+
--objective "Review CI smoke workflow wording"
49+
--owned-files "README.md, tools/README.md"
50+
--out-of-scope "Python implementation"
51+
52+
- name: Acceptance check
53+
run: >
54+
python tools/acceptance_check.py
55+
--scope
56+
--behavior
57+
--verification
58+
--regression
59+
--memory
60+
61+
- name: Close task
62+
run: >
63+
python tools/close_task.py
64+
--memory-dir memory
65+
--task "CI smoke check"
66+
--files "tools/, memory/"
67+
--verification "validate_workflow + acceptance_check"
68+
--risk "No major risk in smoke mode"
69+
70+
- name: Validate workflow templates again
71+
run: python tools/validate_workflow.py --memory-dir memory

‎README.en.md‎

Lines changed: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
# Codex Workflow Kit
2+
3+
English | [Русский](README.md)
4+
5+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
6+
[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](tools/README.md)
7+
[![Repository](https://img.shields.io/badge/GitHub-PEDZEO%2Fcodex--workflow--kit-black.svg)](https://github.com/PEDZEO/codex-workflow-kit)
8+
[![CI](https://github.com/PEDZEO/codex-workflow-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/PEDZEO/codex-workflow-kit/actions/workflows/ci.yml)
9+
10+
Strict workflow kit for Codex: narrow repository search, short working memory, controlled agent delegation, and explicit acceptance before closing work.
11+
12+
Use this repository when you want Codex to:
13+
- keep context between steps;
14+
- avoid wandering through files;
15+
- spend fewer tokens on repeated context;
16+
- delegate with explicit ownership;
17+
- avoid closing tasks without verification.
18+
19+
Repository: `https://github.com/PEDZEO/codex-workflow-kit`
20+
21+
## What It Provides
22+
23+
The system is built around four ideas:
24+
25+
1. One source of truth for the active task
26+
`current-task.md` holds the live state of work and prevents the task from spreading across chat messages and temporary notes.
27+
28+
2. A strict start and search sequence
29+
Codex reads the index and task intake first, then performs narrow search instead of broad repository wandering.
30+
31+
3. Controlled delegation
32+
Each agent gets ownership, out-of-scope boundaries, and a done condition.
33+
34+
4. Explicit acceptance
35+
Work is not considered finished until acceptance gates are passed.
36+
37+
## Requirements
38+
39+
- Git
40+
- Python 3.10+
41+
- `rg` (`ripgrep`) is recommended for fast search
42+
43+
## Installation
44+
45+
### Linux
46+
47+
```bash
48+
git clone https://github.com/PEDZEO/codex-workflow-kit.git
49+
cd codex-workflow-kit
50+
python3 --version
51+
python3 tools/bootstrap.py --target ../my-project
52+
```
53+
54+
If `ripgrep` is not installed yet:
55+
56+
```bash
57+
# Ubuntu / Debian
58+
sudo apt-get update && sudo apt-get install -y ripgrep
59+
60+
# Fedora
61+
sudo dnf install -y ripgrep
62+
63+
# Arch
64+
sudo pacman -S ripgrep
65+
```
66+
67+
### Windows
68+
69+
```powershell
70+
git clone https://github.com/PEDZEO/codex-workflow-kit.git
71+
cd codex-workflow-kit
72+
python --version
73+
python tools/bootstrap.py --target ..\my-project
74+
```
75+
76+
## Mandatory Core
77+
78+
These files are the minimum required set for the workflow to stay strict:
79+
80+
- `AGENTS.md`
81+
- `OPERATING_RULES.md`
82+
- `CODEBASE_INDEX.md`
83+
- `TASK_INTAKE.md`
84+
- `SEARCH_PLAYBOOK.md`
85+
- `FILE_PRIORITY.md`
86+
- `.codex/memory/current-task.md`
87+
- `.codex/memory/handoffs.md`
88+
- `.codex/memory/done.md`
89+
- `ACCEPTANCE_GATES.md`
90+
91+
Without this core, the kit becomes documentation instead of an operating workflow.
92+
93+
## Optional Support Files
94+
95+
These files improve the workflow, but are not part of the absolute minimum:
96+
97+
- `TEST_INDEX.md`
98+
- `CHANGE_AREAS.md`
99+
- `FINAL_REPORT.md`
100+
- `NOISE_FILTER.md`
101+
- `RISK_PATTERNS.md`
102+
- `TASK_SIZE_RULES.md`
103+
- `.codex/memory/decisions.md`
104+
- `templates/`
105+
- `examples/`
106+
107+
## Quick Start
108+
109+
### Linux
110+
111+
```bash
112+
python3 tools/bootstrap.py --target ../my-project
113+
```
114+
115+
### Windows
116+
117+
```powershell
118+
python tools/bootstrap.py --target ..\my-project
119+
```
120+
121+
This bootstraps the mandatory core into the target project without overwriting existing files unless `--force` is used.
122+
123+
### Manual Setup
124+
125+
1. Copy `AGENTS.md` and `OPERATING_RULES.md` into the project root.
126+
2. Copy `CODEBASE_INDEX.md`, `TASK_INTAKE.md`, `SEARCH_PLAYBOOK.md`, `FILE_PRIORITY.md`, and `ACCEPTANCE_GATES.md` into the project root.
127+
3. Create `.codex/memory/` and add:
128+
- `current-task.md`
129+
- `handoffs.md`
130+
- `done.md`
131+
4. Add `.editorconfig` and `.gitattributes`.
132+
5. Fill in `CODEBASE_INDEX.md` and `TASK_INTAKE.md` for the real project.
133+
134+
## Basic Working Loop
135+
136+
Codex should operate like this:
137+
138+
1. Read `CODEBASE_INDEX.md`, `TASK_INTAKE.md`, and `current-task.md`.
139+
2. Build a short plan.
140+
3. Search narrowly: `rg --files` -> `rg` -> targeted reads.
141+
4. Keep live task state only in `current-task.md`.
142+
5. Delegate only tasks with explicit ownership.
143+
6. Pass `ACCEPTANCE_GATES.md` before closing work.
144+
7. Move completed work into `done.md`.
145+
146+
## Python Tools
147+
148+
`tools/` already includes CLI commands that enforce the workflow:
149+
150+
- `bootstrap.py` — bootstrap the mandatory core into a new project
151+
- `scaffold_task.py` — create or replace `current-task.md`
152+
- `create_handoff.py` — append a structured handoff
153+
- `close_task.py` — archive a completed task into `done.md`
154+
- `validate_workflow.py` — validate the mandatory core and memory discipline
155+
- `acceptance_check.py` — explicitly pass acceptance gates
156+
157+
More details and command examples: [tools/README.md](tools/README.md)
158+
159+
## Structure After Bootstrap
160+
161+
```text
162+
my-project/
163+
|-- .codex/
164+
| `-- memory/
165+
| |-- current-task.md
166+
| |-- handoffs.md
167+
| `-- done.md
168+
|-- .editorconfig
169+
|-- .gitattributes
170+
|-- ACCEPTANCE_GATES.md
171+
|-- AGENTS.md
172+
|-- CODEBASE_INDEX.md
173+
|-- FILE_PRIORITY.md
174+
|-- OPERATING_RULES.md
175+
|-- SEARCH_PLAYBOOK.md
176+
`-- TASK_INTAKE.md
177+
```
178+
179+
## Rules That Should Not Drift
180+
181+
1. The active task has one source of truth: `.codex/memory/current-task.md`.
182+
2. Do not start with broad file browsing if the index and intake already exist.
183+
3. Research must collapse into a short summary.
184+
4. Delegation requires ownership and out-of-scope boundaries.
185+
5. Do not close work without an acceptance check.
186+
187+
## Repo Files
188+
189+
- `.editorconfig` — consistent encoding and line endings
190+
- `.gitattributes` — text normalization for Git
191+
- `.gitignore` — local runtime and editor noise
192+
- `LICENSE` — MIT
193+
194+
## Limits
195+
196+
This kit does not try to:
197+
- understand your architecture automatically;
198+
- fill project maps perfectly on its own;
199+
- replace engineering judgment;
200+
- fix poor task decomposition by magic.
201+
202+
Its goal is different: make a good workflow cheap to follow and expensive to ignore.
203+
204+
## Recommended Adoption Order
205+
206+
1. Adopt the mandatory core first.
207+
2. Fill `CODEBASE_INDEX.md`.
208+
3. Add optional support files as needed.
209+
4. Use the Python tools in day-to-day work.
210+
5. Expand the kit only after the core process is stable.
211+
212+
## License
213+
214+
MIT. See [LICENSE](LICENSE).

‎README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,11 @@
11
# Codex Workflow Kit
22

3+
[English](README.en.md) | Русский
4+
35
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
46
[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](tools/README.md)
57
[![Repository](https://img.shields.io/badge/GitHub-PEDZEO%2Fcodex--workflow--kit-black.svg)](https://github.com/PEDZEO/codex-workflow-kit)
8+
[![CI](https://github.com/PEDZEO/codex-workflow-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/PEDZEO/codex-workflow-kit/actions/workflows/ci.yml)
69

710
Строгий workflow-kit для Codex: быстрый поиск по репозиторию, короткая рабочая память, контролируемое делегирование агентам и жесткая приемка результата.
811

‎tools/README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
Эти скрипты превращают markdown-процесс в более жесткий workflow.
44

5+
CI smoke-check for the CLI lives in [`.github/workflows/ci.yml`](../.github/workflows/ci.yml).
6+
57
## Requirements
68

79
- Python 3.10+

0 commit comments

Comments
 (0)