https://github.com/cryptojones/120xsocrates
Interactive CLI that interrogates you Socratic-style and fills out the planning docs for a 120x Operators Kit project (To feed into Claude or Codex)
https://github.com/cryptojones/120xsocrates
120x apache-2 cli interview operators-kit planning python scaffolding socratic
Last synced: 7 days ago
JSON representation
Interactive CLI that interrogates you Socratic-style and fills out the planning docs for a 120x Operators Kit project (To feed into Claude or Codex)
- Host: GitHub
- URL: https://github.com/cryptojones/120xsocrates
- Owner: CryptoJones
- License: other
- Created: 2026-05-18T20:11:37.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-06-10T13:18:34.000Z (9 days ago)
- Last Synced: 2026-06-10T14:05:54.371Z (9 days ago)
- Topics: 120x, apache-2, cli, interview, operators-kit, planning, python, scaffolding, socratic
- Language: Python
- Homepage: https://github.com/CryptoJones/120xSocrates
- Size: 271 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 120xSocrates
Interactive CLI that interrogates you Socratic-style and fills out the planning docs for a [120x Operators Kit](https://120x.ai) project.
[](https://github.com/CryptoJones/120xSocrates/actions/workflows/test.yml)
[](LICENSE)
[](https://codeberg.org/CryptoJones/120xSocrates)
[](https://github.com/CryptoJones/120xSocrates)
[](https://www.python.org/)
[](CHANGELOG.md)
> Mirrored on both [GitHub](https://github.com/CryptoJones/120xSocrates) and
> [Codeberg](https://codeberg.org/CryptoJones/120xSocrates). Issues filed on
> either are welcome; commits are pushed to both.
---
## What it does
The [120x Operators Kit](https://120x.ai) ships a `scaffold.sh` that creates an empty project skeleton — folders for `planning/`, `docs/`, `src/`, plus 20+ blank markdown files (`AGENTS.md`, `STATE.md`, `DECISIONS.md`, `DOMAIN.md`, `RISKS.md`, `QUESTIONS.md`, sprint requirements/blueprint/acceptance, etc.) that the operator is supposed to fill in with content from an "Architect" chat session.
**120xSocrates is the part that actually fills them in.**
Instead of copy-pasting from a browser chat back into your code editor, `socrates` runs at the command line, asks you a structured series of Socratic questions about the project, and writes the answers directly into every planning file in the right shape. One terminal session, no chat thread to manage, no folder of blank `.md`s left behind.
In a single command it will:
1. Run the standard 120x scaffold (creating the folder tree and blank files), or use an existing one.
2. Walk you through 19 questions covering business goal, users, workflow, data, risks, decisions, and Sprint 001 scope.
3. Write the answers into the canonical 120x planning files using the kit's conventions.
4. Print a punch list of any unresolved questions and what to send to the Architect next.
## Quick start
```bash
# install from source
git clone https://github.com/CryptoJones/120xSocrates.git
cd 120xSocrates
# create + activate a virtual environment first, then install into it.
# (modern Linux/macOS block `pip install` into the system Python with an
# "externally-managed-environment" error — the venv is how you avoid that.)
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e .
# note: every new terminal needs `source .venv/bin/activate` before the
# `socrates` command is on your PATH.
# (optional) scaffold the macro layer once
socrates companyos ~/Documents/120x
# scaffold + interview a fresh project
cd ~/Documents/120x/builds
socrates init quarterly-rebates
# every working day, log what happened
cd quarterly-rebates
socrates journal
# verify the planning files stayed consistent (good in CI)
socrates audit
# generate a 60-second briefing for new collaborators
socrates onboard
# at the end of a sprint, capture a reusable pattern
socrates extract
```
## Subcommands
`socrates` ships twelve subcommands. They are designed to be composable —
each one operates on a 120x folder produced by `socrates init` or
`socrates companyos`.
**Per-project commands** (run inside a single `builds//`):
| Subcommand | One-liner |
|---|---|
| `socrates init ` | scaffold a project and interview the operator |
| `socrates audit [path]` | verify planning files for internal consistency |
| `socrates onboard [path]` | produce a 60-second WELCOME.md from existing planning files |
| `socrates journal [path]` | open today's `planning/journal/YYYY-MM-DD.md` entry |
| `socrates decide ""` | append a dated decision to `planning/DECISIONS.md` |
| `socrates extract [path]` | sprint-close interview to capture a reusable pattern |
| `socrates timeline [path]` | chronological feed of journal entries, sprints, and dated decisions |
| `socrates ship [path]` | sprint-close pre-flight: audit + journal + extract + state freshness |
| `socrates pack [path]` | assemble an Architect input bundle for browser chat |
**Macro-level commands** (run at the CompanyOS root):
| Subcommand | One-liner |
|---|---|
| `socrates companyos ` | scaffold the macro layer that wraps per-project builds |
| `socrates status [path]` | one-screen health dashboard for every project in a CompanyOS |
| `socrates patterns review [path]` | scan `patterns/` for stale candidates, orphans, and unused entries |
| `socrates audit --companyos [path]` | macro-level audit (orphan builds/clients/patterns, stale proposals) |
### `socrates init ` — interview a new project
Scaffolds the 120x folder tree and walks the operator through the Socratic interview, then writes the planning files.
| Flag | Effect |
|---|---|
| `--base PATH` | parent dir for the project folder (default: cwd) |
| `--no-scaffold` | skip the scaffold step (folder must exist) |
| `--resume` | resume a partially-completed interview |
| `--no-render` | save answers but skip writing the `.md` files |
| `--editor` | use `$EDITOR` for multi-line answers |
Answers are saved incrementally (and atomically — a kill mid-write can never corrupt the file) to `.socrates-answers.json` inside the project folder, so Ctrl-C is safe and `--resume` picks up where you left off. If a resume file is somehow unreadable, socrates warns and starts fresh instead of crashing. Slugs are validated up front: path separators, `..` segments, and absolute paths are rejected before anything touches disk.
#### Editor mode for prose answers
For longer paragraphs, pass `--editor` and socrates will open `$EDITOR` (honouring `$VISUAL`, falling back to `nano`/`vim`/`vi`) with a tempfile per multi-line question. Comment lines (`#`-prefixed) are stripped on save; an empty file accepts the question's default.
### `socrates audit [path]` — verify an existing project
Scans a populated 120x folder for structural and content issues. Exits non-zero when errors are found, so it slots cleanly into CI:
```bash
socrates audit # audit the current folder
socrates audit ./quarterly-rebates # audit a specific project
socrates audit . --strict # treat warnings as errors
socrates audit . --json # machine-readable output
```
The audit runs eight checks; each was chosen to be high-signal with **zero tolerance for false positives** (a noisy audit gets ignored):
| Check | Severity | What it catches |
|---|---|---|
| `required-files` | ERROR | one of the canonical planning files is missing |
| `sprint-folders` | ERROR | a sprint folder is malformed (bad name, missing one of the 4 required files) |
| `scaffold-shape` | INFO | a scaffold file was pruned (allowed, but worth noting) |
| `adapter-routing` | WARNING | `CLAUDE.md` / `CODEX.md` does not point to `AGENTS.md` |
| `acceptance-weasels` | WARNING | acceptance criteria use vague phrases (`TBD`, `as needed`, `robust enough`, …) |
| `state-freshness` | WARNING | `STATE.md` has not been touched in 30+ days |
| `always-on-risks` | INFO | `RISKS.md` is missing the kit's "AI is not source of truth" reminder |
| `terminology-used` | INFO | a term defined in `DOMAIN.md` is not used anywhere else (dead-weight definition) |
Exit codes: `0` clean (info-only is still clean), `1` errors present (or warnings with `--strict`), `2` invocation error.
To silence `scaffold-shape` notices for files you have deliberately pruned, list them in a `.socrates-audit.json` in the project root:
```json
{"scaffold_shape": {"ignore": ["docs/API.md", "docs/PERMISSIONS.md"]}}
```
### `socrates onboard [path]` — synthesize WELCOME.md
Reads the existing planning files (STATE / DECISIONS / RISKS / QUESTIONS) and writes a one-minute briefing as `WELCOME.md` in the project root. **Pure synthesis** — no interview, no LLM, no third-party calls. Designed for the case where a new collaborator (human or agent) walks in cold.
```bash
socrates onboard # write WELCOME.md in cwd
socrates onboard ./quarterly-rebates # write into a specific project
socrates onboard . --stdout # print to stdout instead of writing
```
The synthesized WELCOME.md contains:
- Project tagline, client, tech stack
- Active sprint (derived from the highest-numbered `planning/sprints/NNN-*` folder, not a stale label), current status, next action
- The 3 most load-bearing decisions — including any added after init via `socrates decide`, freshest first — and 3 explicitly out-of-scope items
- The 3 most prominent risks and open questions
- A pointer to the active sprint folder and the three files to read next
The output is auto-generated. Re-run `socrates onboard` whenever planning state shifts.
### `socrates journal [path]` — append-only daily log
Creates today's `planning/journal/YYYY-MM-DD.md` entry (with a short template) and opens `$EDITOR` so you can fill it in. The journal **complements** `STATE.md`: STATE is the rolling snapshot, journal entries are immutable historical fragments. Only canonically named `YYYY-MM-DD.md` files count as entries — stray notes dropped into the folder are ignored by `--show` and `--list`.
```bash
socrates journal # create + open today's entry
socrates journal --show # print the latest entry
socrates journal --list # list all entries, oldest first
```
When you find yourself wondering "what changed between sprints 003 and 005?", this folder is the answer.
### `socrates extract [path]` — capture a reusable pattern
A sprint-close interview that walks the operator through capturing one reusable pattern from the project that just shipped. The 120x methodology promises three deliverables (the shipped system, the preserved blueprint, and **the extracted pattern**); the third is the one most often skipped.
```bash
socrates extract # interview, write patterns/CANDIDATE-.md
socrates extract --editor # open $EDITOR for the pattern body (recommended)
socrates extract --patterns-dir ../patterns/ # explicit target
```
Auto-detection: if the project sits inside a CompanyOS layout (`builds//`), the pattern is written to the sibling `patterns/` directory so it lives at the macro level where it can compound across projects. Otherwise a local `patterns/` directory inside the project is used.
Pattern files are named `CANDIDATE-.md`. Promote a candidate to a real pattern by dropping the `CANDIDATE-` prefix **only after** it has worked on at least one additional project.
### `socrates pack [path]` — assemble an Architect input bundle
Concatenates every load-bearing planning file (AGENTS, README, STATE, DOMAIN, DECISIONS, RISKS, QUESTIONS) plus the active sprint's four files into one paste-able bundle for the Architect (Claude Chat / ChatGPT / etc.). Output goes to `.socrates-architect-pack.` in the project root, or to stdout with `--stdout`.
```bash
socrates pack # write .socrates-architect-pack.md
socrates pack --stdout # print to stdout
socrates pack --sprint 002-rebate-engine # override the auto-detected sprint
socrates pack --include-philosophy # prepend socrates' own 120x stance summary
socrates pack --kit-path ~/120x-kit # also embed the kit's three load-bearing files
socrates pack --format xml # XML section delimiters around markdown bodies
socrates pack --format html # full HTML (requires the [html] extra)
```
| Flag | Effect |
|---|---|
| `--sprint ` | include this sprint folder instead of auto-detecting the highest-numbered one |
| `--stdout` | print to stdout instead of writing the file |
| `--include-philosophy` | prepend a short, original 120x stance written by socrates |
| `--kit-path PATH` | also embed the kit's three load-bearing files (or use `$SOCRATES_KIT_PATH`) |
| `--format md\|html\|xml` | output format. `md` (default), `xml` (markdown wrapped in `` tags — matches Anthropic's prompt-engineering recommendation), `html` (full HTML, requires `pip install socrates120x[html]`) |
The output file extension follows the format: `.md`, `.xml`, or `.html`. The default `md` keeps the historical behavior. `xml` adds ~5% token overhead but gives the Architect explicit structural delimiters. `html` adds ~30-50% token overhead and requires the optional `markdown` dependency — use it when you're explicitly testing whether full HTML helps the Architect on your specific content. HTML output carries a strict Content-Security-Policy meta tag (no scripts, frames, or external resources), so previewing a bundle that contains pasted third-party content cannot execute anything in your browser.
### `socrates companyos ` — scaffold the macro layer
Creates the CompanyOS skeleton: `clients/`, `builds/`, `pipeline/`, `patterns/`, `content/`, `reference/`, `daily/`, `templates/`, plus an `AGENTS.md` router that points each subfolder at its role.
```bash
socrates companyos ~/Documents/120x
```
Per the 120x philosophy, the CompanyOS is the macro operating system that wraps every per-project build. Per-project state lives in `builds//`; long-lived assets (extracted patterns, client context, pipeline notes) live at the CompanyOS root. Use this once when setting up the factory; thereafter `socrates init builds/` from inside it.
## How the `init` interview is structured
The questions follow the 120x Operators Kit's own document layout, so each answer maps to exactly one place in the resulting folder:
| Section | Asks about | Populates |
|---|---|---|
| Project Identity | name, client, tagline, tech stack | `README.md`, `AGENTS.md` |
| Domain | client terminology, users, workflow, current process | `planning/DOMAIN.md` |
| Decisions | architectural choices already made, things explicitly out of scope | `planning/DECISIONS.md` |
| Risks | known traps, fragile inputs, scope creep flags | `planning/RISKS.md` |
| Open Questions | things you don't know yet | `planning/QUESTIONS.md` |
| Sprint 001 | discovery goal, acceptance criteria, handoff prompt | `planning/sprints/001-discovery-architecture/*.md` |
| State | current status, next action | `planning/STATE.md` |
Questions you cannot answer are written verbatim to `QUESTIONS.md` rather than guessed — that's the Socratic part. The Architect ([Claude Chat](https://claude.ai) or ChatGPT) can then pick up the question list directly.
## Requirements
- Python 3.10+. No third-party dependencies for runtime; just the standard library.
The implementation is eight modules grouped by role, reading in dependency layers (each file is digestible on its own; [`cli.py`](src/socrates120x/cli.py) is the main file that calls the rest):
| Module | Role |
|---|---|
| `support.py` | plumbing: terminal colors, atomic file I/O, prompting primitives — no 120x knowledge |
| `kit.py` | the canonical 120x shapes: scaffold, planning-file renderers, CompanyOS layer |
| `interview.py` | the init question set + resumable runner |
| `audit.py` | findings model + every check + runner + report |
| `operate.py` | daily rituals: decide, journal, timeline, ship, status |
| `patterns.py` | the pattern lifecycle: extract (create) + review (drift) |
| `synthesize.py` | derived docs: onboard (WELCOME.md) + pack (Architect bundle) |
| `cli.py` | argparse wiring and dispatch |
See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the dependency rule, the load-bearing invariants (kit byte-compatibility, atomic writes, no-false-positive audits), and the on-disk data files.
The folder structure socrates produces matches the [120x Operators Kit](https://120x.ai) scaffold byte-for-byte, but socrates does not require the kit to be installed locally — the structure is baked in.
## Why this exists
The [Operators Kit](https://120x.ai) is great. The four-step workflow is great. But Step 4 — "have the Builder populate the empty files from the Architect's pasted output" — is the friction point: it requires a browser chat session and a paste-back loop.
For projects where the operator already has the answers in their head (and most consulting work is like this), going through a chat thread to produce the planning pack is overkill. 120xSocrates collapses that loop into a single terminal interview that produces the same output, with the same structure, in less time.
## License
Apache 2.0. See [LICENSE](LICENSE).
Not affiliated with or endorsed by 120x.ai — this is an independent tool that consumes the publicly-published Operators Kit.
Proudly Made in Nebraska. Go Big Red! 🌽 https://xkcd.com/2347/