Skip to content

Commit 21617d0

Browse files
sdntsngsdntsng
committed
Add open-source docs and validation workflow
1 parent aa05219 commit 21617d0

5 files changed

Lines changed: 246 additions & 21 deletions

File tree

‎.github/workflows/validate.yml‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
name: validate
2+
3+
on:
4+
push:
5+
pull_request:
6+
7+
jobs:
8+
validate:
9+
runs-on: ubuntu-latest
10+
steps:
11+
- uses: actions/checkout@v4
12+
- uses: actions/setup-python@v5
13+
with:
14+
python-version: '3.11'
15+
- run: python3 scripts/check_repo.py

‎CONTRIBUTING.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Contributing
2+
3+
## Principles
4+
- Keep skills concise.
5+
- Keep Codex-native instructions in `skills/`.
6+
- Do not copy Claude-specific boilerplate from upstream `gstack`.
7+
- Preserve workflow value, not source formatting.
8+
9+
## When upstream gstack changes
10+
1. Pull or update your local `gstack` checkout.
11+
2. Run:
12+
13+
```bash
14+
python3 scripts/sync_from_gstack.py status --source <gstack-path>
15+
python3 scripts/sync_from_gstack.py scaffold-new --source <gstack-path>
16+
```
17+
18+
3. Review any newly generated folders under `scaffolds/`.
19+
4. Promote the useful ones into curated skills under `skills/`.
20+
5. Update `mappings/skills.json` when a scaffold becomes a curated skill.
21+
22+
## Skill authoring rules
23+
- Frontmatter should be minimal and precise.
24+
- Put detailed knowledge in references only when it materially improves repeatability.
25+
- Prefer workflow instructions over slogans.
26+
- Mention when the skill should stop and surface uncertainty.
27+
28+
## Validation
29+
Run:
30+
31+
```bash
32+
python3 scripts/check_repo.py
33+
```
34+
35+
## Local install
36+
To install or refresh links into your Codex setup:
37+
38+
```bash
39+
python3 scripts/sync_from_gstack.py install --target ~/.codex/skills
40+
```

‎README.md‎

Lines changed: 111 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,115 @@
11
# codex-gstack
22

3-
Codex-native workflow skills inspired by gstack.
3+
Codex-native workflow skills inspired by `gstack`.
44

5-
This repo packages a clean, Codex-first set of specialist skills for:
6-
- browser dogfooding
7-
- systematic debugging
8-
- web QA
9-
- preflight review
5+
`codex-gstack` is a public skill pack for Codex users who want structured specialist workflows instead of ad hoc prompting. It ports the highest-value ideas from `gstack` into concise, Codex-first skills and adds a lightweight sync pipeline so new upstream `gstack` skills can be detected and scaffolded quickly.
6+
7+
## What this repo includes
8+
9+
### Core engineering skills
10+
- `browser-dogfood`
11+
- `systematic-debugging`
12+
- `web-qa-report`
13+
- `web-qa-fix`
14+
- `pr-preflight-review`
15+
- `doc-sync-after-change`
16+
- `ship`
17+
18+
### Founder and planning skills
19+
- `office-hours`
20+
- `plan-ceo-review`
21+
- `plan-eng-review`
22+
23+
### Design and execution skills
24+
- `design-consultation`
25+
- `design-review-live`
26+
- `project-retro`
27+
28+
## Why this exists
29+
`gstack` has strong workflow ideas, but it is optimized for Claude Code and carries a lot of Claude-specific ceremony. This repo focuses on the reusable part:
30+
- specialist roles
31+
- real browser testing
32+
- root-cause-first debugging
33+
- diff-aware review
1034
- documentation sync
11-
- release readiness
12-
- founder and planning reviews
13-
- design consultation and design review
14-
- project retrospectives
15-
16-
It is designed to be:
17-
- open source
18-
- installable into `~/.codex/skills`
19-
- maintainable as upstream `gstack` evolves
20-
- concise and Codex-native rather than Claude-specific
21-
22-
This repository is being built in stages:
23-
1. baseline skill pack
24-
2. gstack sync and scaffold tooling
25-
3. public release docs and install flow
35+
- product and planning reviews
36+
37+
The goal is not to mirror upstream line-for-line. The goal is to keep the workflow value and remove the environment-specific overhead.
38+
39+
## Install locally
40+
41+
To link all skills from this repo into your local Codex setup:
42+
43+
```bash
44+
python3 scripts/sync_from_gstack.py install --target ~/.codex/skills
45+
```
46+
47+
That creates symlinks from this repo's `skills/` directory into `~/.codex/skills`.
48+
49+
## Track upstream gstack changes
50+
51+
If you have a local `gstack` checkout available, generate a fresh sync report and scaffold any newly discovered skills:
52+
53+
```bash
54+
./scripts/update-from-local-gstack.sh ../knowledge-base/gstack
55+
```
56+
57+
Or run the steps explicitly:
58+
59+
```bash
60+
python3 scripts/sync_from_gstack.py status --source ../knowledge-base/gstack
61+
python3 scripts/sync_from_gstack.py scaffold-new --source ../knowledge-base/gstack
62+
```
63+
64+
This will:
65+
- refresh `catalog/gstack-sync-status.md`
66+
- detect upstream skills not yet mapped
67+
- scaffold starter Codex skill folders under `scaffolds/`
68+
69+
## Repo structure
70+
71+
```text
72+
skills/ curated Codex-native skills
73+
mappings/skills.json upstream gstack -> codex-gstack mapping
74+
catalog/ generated status output
75+
scaffolds/ auto-created starter ports for new upstream skills
76+
scripts/ sync, install, and validation tooling
77+
docs/ porting notes and contributor docs
78+
```
79+
80+
## Current porting model
81+
82+
Mapped upstream skills become curated Codex skills.
83+
84+
Unmapped upstream skills are not ignored. They are scaffolded automatically so a contributor can finish the port quickly instead of starting from zero.
85+
86+
That means this repo supports both:
87+
- a stable curated skill pack
88+
- a fast path for adopting new upstream `gstack` skills
89+
90+
## Validation
91+
92+
Run:
93+
94+
```bash
95+
python3 scripts/check_repo.py
96+
```
97+
98+
This checks:
99+
- every curated skill has `SKILL.md`
100+
- every curated skill has `agents/openai.yaml`
101+
- the mapping file is valid JSON
102+
- every mapped target exists in `skills/`
103+
104+
## Contribution workflow
105+
106+
1. Add or refine a skill in `skills/`
107+
2. Run `python3 scripts/check_repo.py`
108+
3. If syncing from upstream, run `python3 scripts/sync_from_gstack.py status --source <path>`
109+
4. Commit one logical change at a time
110+
111+
Detailed guidance lives in `CONTRIBUTING.md` and `docs/porting-guide.md`.
112+
113+
## License
114+
115+
MIT

‎docs/porting-guide.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Porting Guide
2+
3+
## Goal
4+
Turn strong upstream `gstack` workflows into concise Codex-native skills.
5+
6+
## Keep
7+
- role clarity
8+
- explicit workflow phases
9+
- real-world testing and verification habits
10+
- decision points that reduce bad automation
11+
12+
## Remove
13+
- repeated preambles
14+
- upgrade choreography
15+
- contributor-mode logs
16+
- Claude-specific tool references
17+
- hardcoded `.claude/skills/...` paths
18+
- motivational filler repeated in every skill
19+
20+
## Good Codex ports usually have
21+
- a sharp trigger description
22+
- a short workflow section
23+
- explicit output expectations
24+
- a small number of guardrails
25+
26+
## Bad ports usually have
27+
- giant copied markdown bodies
28+
- environment-specific setup that does not apply to Codex
29+
- ambiguous invocation criteria
30+
- too much philosophy and too little procedure
31+
32+
## Fast path for new upstream skills
33+
When a new upstream skill appears:
34+
1. run `sync_from_gstack.py scaffold-new`
35+
2. inspect the generated scaffold under `scaffolds/`
36+
3. decide whether it belongs in the curated pack
37+
4. if yes, create a polished version under `skills/`
38+
5. add the mapping entry

‎scripts/check_repo.py‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
#!/usr/bin/env python3
2+
from __future__ import annotations
3+
4+
import json
5+
import sys
6+
from pathlib import Path
7+
8+
ROOT = Path(__file__).resolve().parents[1]
9+
SKILLS_DIR = ROOT / 'skills'
10+
MAPPINGS_PATH = ROOT / 'mappings' / 'skills.json'
11+
12+
13+
def fail(message: str) -> None:
14+
print(f'ERROR: {message}')
15+
sys.exit(1)
16+
17+
18+
def main() -> None:
19+
if not SKILLS_DIR.exists():
20+
fail('skills directory missing')
21+
if not MAPPINGS_PATH.exists():
22+
fail('mappings/skills.json missing')
23+
24+
data = json.loads(MAPPINGS_PATH.read_text())
25+
if 'mapped_skills' not in data or not isinstance(data['mapped_skills'], list):
26+
fail('mapped_skills must be a list')
27+
28+
for item in data['mapped_skills']:
29+
target = item['target']
30+
skill_dir = SKILLS_DIR / target
31+
if not skill_dir.exists():
32+
fail(f'mapped target missing: {target}')
33+
if not (skill_dir / 'SKILL.md').exists():
34+
fail(f'SKILL.md missing for {target}')
35+
if not (skill_dir / 'agents' / 'openai.yaml').exists():
36+
fail(f'agents/openai.yaml missing for {target}')
37+
38+
print('Repo structure looks valid.')
39+
40+
41+
if __name__ == '__main__':
42+
main()

0 commit comments

Comments
 (0)