Skip to content

Commit 6a166f7

Browse files
committed
add build command and cookbook for split pipeline workflows
Add `phalus build` CLI command that runs Agent B from an existing CSP manifest on disk, enabling a split pipeline where Agent A and Agent B run as separate steps. This allows CSP review, modification (e.g. injecting custom security constraints), and multi-language builds from a single specification. New documentation: - cookbook.md with recipes for all split pipeline workflows - Updated cli-reference.md with build command docs - Updated getting-started.md, pipeline.md, and index.md with cross-references Bump version to 0.3.0.
1 parent b2ebc8c commit 6a166f7

9 files changed

Lines changed: 618 additions & 4 deletions

File tree

Cargo.lock

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

Cargo.toml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[package]
22
name = "phalus"
3-
version = "0.2.0"
3+
version = "0.3.0"
44
edition = "2021"
55
license = "0BSD"
66
description = "Private Headless Automated License Uncoupling System — AI-powered clean room software reimplementation"

docs/cli-reference.md

Lines changed: 67 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ Run `phalus --help` for a summary or `phalus [COMMAND] --help` for per-command h
1717
| [`plan`](#plan) | Parse a manifest and show what would be processed |
1818
| [`run`](#run) | Run the full clean room pipeline from a manifest |
1919
| [`run-one`](#run-one) | Run the pipeline on a single package without a manifest |
20+
| [`build`](#build) | Run Agent B only from an existing CSP |
2021
| [`inspect`](#inspect) | Inspect a completed job's output directory |
2122
| [`validate`](#validate) | Re-run validation on an existing output directory |
2223
| [`config`](#config) | Print the active configuration (API keys redacted) |
@@ -95,7 +96,7 @@ phalus run <MANIFEST> [OPTIONS]
9596
| `--isolation <mode>` | `context` | Isolation strategy: `context`, `process`, `container` |
9697
| `--similarity-threshold <f>` | `0.70` | Similarity score above which a package is flagged as FAIL |
9798
| `--concurrency <n>` | `3` | Number of packages to process in parallel |
98-
| `--dry-run` | false | Run Agent A only (produce CSP specs), skip Agent B and validation |
99+
| `--dry-run` | false | Run Agent A only produce CSP specs, skip Agent B and validation. Use with [`build`](#build) for a split workflow. |
99100
| `--verbose` | false | Enable verbose logging |
100101

101102
### Exit codes
@@ -120,9 +121,13 @@ phalus run package.json --only lodash,express
120121
# Reimplement JavaScript packages in Rust
121122
phalus run package.json --target-lang rust --license apache-2.0
122123

123-
# Dry run: produce specs only, no code generation
124+
# Dry run: trigger Agent A only, produce CSP specs without code generation
124125
phalus run package.json --dry-run
125126

127+
# Dry run a single package, then build from the CSP later
128+
phalus run-one npm/lodash@4.17.21 --dry-run
129+
phalus build ./phalus-output/lodash/.cleanroom/csp/
130+
126131
# Stricter similarity threshold
127132
phalus run package.json --similarity-threshold 0.50
128133

@@ -175,6 +180,66 @@ phalus run-one crates/serde@1.0.193 --isolation process
175180

176181
---
177182

183+
## build
184+
185+
Run Agent B (Builder) from an existing Clean Room Specification Pack without re-running Agent A. This is the second half of the split pipeline workflow:
186+
187+
1. Generate a CSP with `--dry-run` (Agent A only)
188+
2. Optionally review or modify the CSP files on disk
189+
3. Run `build` to implement from the CSP (Agent B only)
190+
191+
```
192+
phalus build <CSP> [OPTIONS]
193+
```
194+
195+
### Arguments
196+
197+
| Argument | Description |
198+
|----------|-------------|
199+
| `CSP` | Path to a CSP `manifest.json` file, **or** a directory containing one (e.g. `./phalus-output/lodash/.cleanroom/csp/`) |
200+
201+
### Options
202+
203+
| Option | Default | Description |
204+
|--------|---------|-------------|
205+
| `--license <id>` | `mit` | SPDX license identifier for the generated code |
206+
| `--output <dir>` | `./phalus-output` | Output directory |
207+
| `--target-lang <lang>` | Same as source | Target language: `rust`, `go`, `python`, `typescript` |
208+
| `--isolation <mode>` | `context` | Isolation mode: `context`, `process`, `container` |
209+
| `--similarity-threshold <f>` | `0.70` | Similarity threshold |
210+
| `--verbose` | false | Enable verbose logging |
211+
212+
### Examples
213+
214+
```bash
215+
# Build from a CSP directory (looks for manifest.json inside)
216+
phalus build ./phalus-output/lodash/.cleanroom/csp/
217+
218+
# Build from a specific manifest.json
219+
phalus build ./my-specs/lodash-csp/manifest.json --license apache-2.0
220+
221+
# Build in a different language
222+
phalus build ./phalus-output/chalk/.cleanroom/csp/ --target-lang rust
223+
224+
# Full split workflow: generate CSP, review it, then build
225+
phalus run-one npm/express@4.18.2 --dry-run
226+
# ... inspect and optionally edit the CSP files ...
227+
phalus build ./phalus-output/express/.cleanroom/csp/ --license mit
228+
```
229+
230+
### Split pipeline workflow
231+
232+
The `build` command enables a split pipeline where Agent A and Agent B run as separate steps. This is useful for:
233+
234+
- **Reviewing the CSP** before committing to implementation
235+
- **Injecting custom constraints** into the specification (e.g. security requirements in `03-behavior-spec.md` or `04-edge-cases.md`)
236+
- **Reusing a CSP** to generate implementations in multiple languages
237+
- **Iterating on the implementation** without re-running analysis
238+
239+
See the [Cookbook](cookbook.md) for detailed examples of these workflows.
240+
241+
---
242+
178243
## inspect
179244

180245
Display the contents of a completed job's output directory. With no flags, all sections are shown. Use individual flags to show only what you need.

0 commit comments

Comments
 (0)