@structor-dev/cli 0.1.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (65) hide show
  1. package/CHANGELOG.md +56 -0
  2. package/README.md +131 -21
  3. package/ROADMAP.md +38 -0
  4. package/SECURITY.md +33 -0
  5. package/bin/structor.mjs +561 -29
  6. package/contrib/self-harness/files/README.md +32 -0
  7. package/contrib/self-harness/files/ai/AGENTS.md +35 -0
  8. package/contrib/self-harness/files/ai/ARCHITECTURE.md +38 -0
  9. package/contrib/self-harness/files/ai/HUB.md +59 -0
  10. package/contrib/self-harness/files/ai/PRODUCT.md +36 -0
  11. package/contrib/self-harness/files/ai/QUALITY.md +31 -0
  12. package/contrib/self-harness/files/ai/context.md +38 -0
  13. package/contrib/self-harness/files/scripts/check-workspace.mjs +72 -0
  14. package/contrib/self-harness/harness.config.json +37 -0
  15. package/docs/CONTRIBUTOR-SETUP.md +45 -0
  16. package/docs/INIT.md +55 -2
  17. package/docs/public-launch.md +150 -0
  18. package/examples/anthropic-only/harness.config.json +26 -0
  19. package/examples/frontend-backend/harness.config.json +8 -8
  20. package/examples/generated-harness-tree.md +432 -0
  21. package/examples/openai-and-anthropic/harness.config.json +7 -7
  22. package/examples/single-repo/harness.config.json +7 -7
  23. package/harness.config.example.json +1 -1
  24. package/package.json +12 -4
  25. package/schemas/contract-manifest.schema.json +0 -1
  26. package/schemas/harness-config.schema.json +5 -2
  27. package/scripts/check-config.mjs +20 -31
  28. package/scripts/check-examples.mjs +146 -0
  29. package/scripts/check-placeholders.mjs +2 -0
  30. package/scripts/check-public-hygiene.mjs +249 -0
  31. package/scripts/check-schemas.mjs +42 -0
  32. package/scripts/check-template-files.mjs +15 -98
  33. package/scripts/generated-harness-contract.mjs +416 -0
  34. package/scripts/init-harness.mjs +227 -139
  35. package/scripts/lib.mjs +462 -12
  36. package/scripts/rendered-config.mjs +109 -0
  37. package/scripts/setup-contributor.mjs +125 -0
  38. package/scripts/smoke-template.mjs +260 -73
  39. package/template/AGENTS.md.tpl +4 -2
  40. package/template/README.md.tpl +5 -0
  41. package/template/ai/CODEX-HOOKS.md.tpl +1 -1
  42. package/template/ai/HARNESS-ENGINEERING.md.tpl +5 -2
  43. package/template/ai/HARNESS.md.tpl +4 -1
  44. package/template/ai/contracts/codex-hooks.contract.json.tpl +58 -1
  45. package/template/ai/contracts/codex-hooks.md.tpl +6 -0
  46. package/template/ai/contracts/release-flow.md.tpl +1 -1
  47. package/template/ai/templates/fixtures/issues/valid-ready.md.tpl +3 -1
  48. package/template/ai/templates/issue-template.md.tpl +3 -1
  49. package/template/ai/workspace/LOCAL-STACK.md.tpl +1 -1
  50. package/template/ai/workspace/SYSTEM-MAP.md.tpl +2 -2
  51. package/template/consumer/AGENTS.md.tpl +4 -4
  52. package/template/consumer/CLAUDE.md.tpl +4 -4
  53. package/template/scripts/bootstrap-workspace.mjs.tpl +11 -25
  54. package/template/scripts/check-claude-compatibility.mjs.tpl +62 -9
  55. package/template/scripts/check-codex-hooks.mjs.tpl +262 -20
  56. package/template/scripts/check-template-governance.mjs.tpl +2 -114
  57. package/template/scripts/check-workspace.mjs.tpl +27 -103
  58. package/template/scripts/check-worktree-bootstrap-fixtures.mjs.tpl +12 -0
  59. package/template/scripts/generate-html-views.mjs.tpl +357 -56
  60. package/template/scripts/generated-harness-contract.mjs.tpl +1 -0
  61. package/template/scripts/hooks/lib/codex-hooks-core.mjs.tpl +14 -3
  62. package/template/scripts/lib/path-safety.mjs.tpl +87 -0
  63. package/template/scripts/lib/worktree-bootstrap.mjs.tpl +16 -13
  64. package/template/scripts/validate-governance.mjs.tpl +52 -36
  65. package/schemas/task-brief.schema.json +0 -37
@@ -0,0 +1,32 @@
1
+ # Structor Self-Harness
2
+
3
+ This generated harness guides work on the Structor source repository. Structor
4
+ is the toolkit that generates repository-local AI engineering harnesses.
5
+ Harness engineering is the practice Structor supports.
6
+
7
+ ## Workspace
8
+
9
+ Expected local shape:
10
+
11
+ ```text
12
+ workspace/
13
+ structor/ # source repo contributors edit
14
+ structor-self/ # generated self-harness
15
+ ```
16
+
17
+ ## Start Here
18
+
19
+ 1. `./AGENTS.md`
20
+ 2. `./ai/AGENTS.md`
21
+ 3. `./ai/HUB.md`
22
+ 4. `./ai/context.md`
23
+ 5. The smallest topical doc selected by the hub
24
+
25
+ ## Validation
26
+
27
+ - Validate this self-harness with `node scripts/validate-governance.mjs`.
28
+ - Validate workspace routing with `node scripts/check-workspace.mjs`.
29
+ - Validate Structor source changes from `../structor` with `npm run validate`.
30
+
31
+ Keep this repository as guidance and policy. Do not add runner behavior,
32
+ orchestration, PR automation, or external-service mutation here.
@@ -0,0 +1,35 @@
1
+ # Structor Self-Harness Shared AI Guide
2
+
3
+ This folder holds canonical guidance for contributing to Structor itself.
4
+
5
+ ## Scope
6
+
7
+ - Structor-specific contribution boundaries and review habits.
8
+ - Context routing for generator, template, schema, CLI, and docs changes.
9
+ - Validation expectations for issue work in the Structor source repo.
10
+
11
+ ## Rules
12
+
13
+ - Structor is the toolkit/product. Harness engineering is the practice.
14
+ - Structor is a generator, not a runner, orchestrator, agent runtime, PR
15
+ automation system, dashboard, or external-service integration layer.
16
+ - Keep active templates in `../structor/template/**` generic and reusable.
17
+ - Keep shared guidance model-neutral. Keep model overlays and consumer
18
+ entrypoints thin. Canonical generated policy belongs in
19
+ `../structor/template/ai/*`.
20
+ - Generated self-harness content belongs in this repository or
21
+ `../structor/contrib/self-harness/**`, not in the active generic templates.
22
+ - Issue work should be narrow, regression-driven, and validated before review.
23
+ - Use `npm run validate` in `../structor` as the default full local gate.
24
+ - Use `node scripts/validate-governance.mjs` here after changing self-harness
25
+ guidance.
26
+
27
+ ## Read Order
28
+
29
+ 1. `./ai/context.md`
30
+ 2. `./ai/HUB.md`
31
+ 3. `./ai/PRODUCT.md`
32
+ 4. `./ai/ARCHITECTURE.md`
33
+ 5. `./ai/QUALITY.md`
34
+
35
+ Load additional files only when the task clearly needs them.
@@ -0,0 +1,38 @@
1
+ # Structor Architecture
2
+
3
+ This document maps the parts of the Structor source repo agents most often need
4
+ for narrow contribution work.
5
+
6
+ ## System Shape
7
+
8
+ - `../structor/bin/structor.mjs`: public CLI commands and guided setup.
9
+ - `../structor/scripts/init-harness.mjs`: deterministic harness renderer.
10
+ - `../structor/scripts/lib.mjs`: config resolution, path boundaries, and write
11
+ safety helpers.
12
+ - `../structor/scripts/generated-harness-contract.mjs`: generated artifact and
13
+ validator contract.
14
+ - `../structor/scripts/rendered-config.mjs`: template value rendering.
15
+ - `../structor/template/**`: generic generated-harness templates.
16
+ - `../structor/schemas/**`: config and task schemas.
17
+ - `../structor/test/**`: regression coverage for CLI, config, rendering, and
18
+ path safety.
19
+ - `../structor/contrib/self-harness/**`: Structor-specific self-harness source.
20
+
21
+ ## Ownership Boundaries
22
+
23
+ - Generic generated policy belongs in `../structor/template/ai/*`.
24
+ - Structor-specific contributor guidance belongs in
25
+ `../structor/contrib/self-harness/**` and the generated `structor-self`
26
+ sibling.
27
+ - CLI convenience can prepare local files, but it must not clone, push, open PRs,
28
+ require GitHub auth, or mutate remote services for this manual path.
29
+ - Path and write-safety changes belong close to `scripts/lib.mjs` and must have
30
+ regression coverage.
31
+
32
+ ## Change Guidance
33
+
34
+ - Keep issue work small and tied to the live issue acceptance criteria.
35
+ - Add regression tests for behavioral changes in scripts or validators.
36
+ - Prefer existing helpers over new abstractions.
37
+ - Treat `template/**/*.tpl` as shipped runtime surface, not inert docs.
38
+ - Validate generated output when changing templates or rendering behavior.
@@ -0,0 +1,59 @@
1
+ # Structor Self-Harness Hub
2
+
3
+ This is the routing layer for work on Structor.
4
+
5
+ ## Baseline
6
+
7
+ Always read:
8
+
9
+ - `./AGENTS.md`
10
+ - `./ai/AGENTS.md`
11
+ - `./ai/context.md`
12
+
13
+ ## Routing
14
+
15
+ - Product language, naming, or contribution boundaries:
16
+ `./ai/PRODUCT-SUMMARY.md`, `./ai/PRODUCT.md`
17
+ - Generator flow, template boundaries, config resolution, or write safety:
18
+ `./ai/ARCHITECTURE.md`, `./ai/DESIGN.md`
19
+ - Validation, review evidence, or issue completion:
20
+ `./ai/QUALITY.md`, `./ai/READINESS.md`, `./ai/DECISIONS.md`
21
+ - Harness policy, active generic templates, model overlays, or consumer
22
+ entrypoints:
23
+ `./ai/HARNESS.md`, `./ai/HARNESS-ENGINEERING.md`,
24
+ `./ai/workspace/REPOS.md`, `./ai/workspace/SYSTEM-MAP.md`,
25
+ `./ai/workspace/SESSION-BOOTSTRAP.md`, `./ai/workspace/LOCAL-STACK.md`,
26
+ `./ai/workspace/TEST-STRATEGY.md`
27
+ - Runner, orchestration, automation, future contributor bootstrap, or
28
+ external-service boundaries:
29
+ `./ai/WORKFLOW.md`, `./ai/RUNNER-SAFETY.md`,
30
+ `./ai/RUNNER-READINESS.md`, `./ai/VERSIONING.md`
31
+ - Codex hook surfaces, repo-local hooks, or client safety:
32
+ `./ai/CODEX-HOOKS.md`
33
+ - Contracts, protected surfaces, and release or GitHub safety:
34
+ `./ai/contracts/README.md` and the matching contract doc
35
+ - Task-shape or issue-template changes:
36
+ `./ai/templates/README.md` and the matching template
37
+ - Generated HTML review views:
38
+ `./ai/views/index.html` plus canonical Markdown, JSON, and YAML sources
39
+ - Review requests:
40
+ `./ai/skills/README.md` and the matching review skill
41
+ - Repeated agent mistakes:
42
+ `./ai/AGENT-GARBAGE-COLLECTION.md`
43
+
44
+ ## Source Docs
45
+
46
+ Ground Structor-specific claims in the source repo:
47
+
48
+ - `../structor/README.md`
49
+ - `../structor/CONTEXT.md`
50
+ - `../structor/CONTRIBUTING.md`
51
+ - `../structor/docs/adr/*`
52
+ - `../structor/scripts/**`
53
+ - `../structor/template/**`
54
+
55
+ ## Load Rules
56
+
57
+ - Load the smallest doc set that can answer the task.
58
+ - Prefer current source files over memory or generated summaries.
59
+ - Keep generated self-harness guidance out of active generic templates.
@@ -0,0 +1,36 @@
1
+ # Structor Product Context
2
+
3
+ Structor is early infrastructure for harness engineering. It generates
4
+ repository-local AI engineering harnesses for consumer repositories.
5
+
6
+ ## Product Model
7
+
8
+ - **Structor** is the toolkit and CLI.
9
+ - **Harness engineering** is the practice of shaping durable AI guidance,
10
+ contracts, routing, and validation for software work.
11
+ - **Generated harnesses** are sibling repositories that own guidance, contracts,
12
+ review templates, and validators for a project workspace.
13
+ - **Consumer repositories** own implementation, runtime behavior, tests, and
14
+ deployment-specific details.
15
+ - **Structor Self-Harness** is a generated harness whose consumer repository is
16
+ Structor itself.
17
+
18
+ ## User Promise
19
+
20
+ Structor should help contributors and teams make agent work more reliable by
21
+ turning guidance into versioned local files plus mechanical checks. It should
22
+ stay local, deterministic, inspectable, and conservative.
23
+
24
+ ## Non-Goals
25
+
26
+ - Do not turn Structor into a runner or orchestrator.
27
+ - Do not add polling, PR automation, auto-merge, dashboards, or external writes
28
+ to core Structor.
29
+ - Do not put Structor-specific product content into active generic templates.
30
+ - Do not build the future `structor contribute structor` command until the
31
+ self-harness guidance is worth showing.
32
+
33
+ ## Source Evidence
34
+
35
+ Use `../structor/README.md`, `../structor/CONTEXT.md`, and
36
+ `../structor/CONTRIBUTING.md` as the current terminology sources.
@@ -0,0 +1,31 @@
1
+ # Structor Contribution Quality
2
+
3
+ Keep Structor changes small, evidence-backed, and easy to review.
4
+
5
+ | Domain | Grade | Evidence | Enforced by | Blocking gaps |
6
+ | --- | --- | --- | --- | --- |
7
+ | Product boundary | A | `README.md`, `CONTEXT.md`, `CONTRIBUTING.md` | Manual review | Keep runner behavior out of Structor core |
8
+ | Generic templates | A | `template/**`, `scripts/generated-harness-contract.mjs` | `npm run validate` | Do not add Structor-specific content to active templates |
9
+ | Path safety | A | `scripts/lib.mjs`, `test/init-harness.test.mjs` | `npm test` | Add exploit-shaped regressions for write-path changes |
10
+ | Contributor setup | B | `contrib/self-harness/**`, `scripts/setup-contributor.mjs` | Manual setup validation | Keep future bootstrap out of this path |
11
+ | Issue work | A | Live issue scope and regression evidence | Review | Avoid opportunistic refactors |
12
+ | Readiness | B | `ai/READINESS.md`, `scripts/check-readiness.mjs` | `node scripts/validate-governance.mjs` | Preserve the manual-review state for skipped source entrypoints |
13
+
14
+ ## Completion Checklist
15
+
16
+ - The diff is scoped to the issue.
17
+ - Generic templates remain reusable for consumer projects.
18
+ - Source-repo pointer files are previewed and existing files are skipped unless
19
+ force is explicit.
20
+ - `npm run validate` passes in `../structor`.
21
+ - `npm run setup:contributor -- --dry-run` previews generated self-harness and
22
+ source pointer writes.
23
+ - `npm run setup:contributor` generates or refreshes `../structor-self`.
24
+ - `node scripts/validate-governance.mjs` passes in `../structor-self`.
25
+ - `node scripts/check-workspace.mjs` passes in `../structor-self`.
26
+
27
+ ## Review Posture
28
+
29
+ Lead with risks, regressions, and missing evidence. Summaries come after
30
+ findings. When there are no findings, say that directly and name any remaining
31
+ test gaps.
@@ -0,0 +1,38 @@
1
+ # Structor Self-Harness Context
2
+
3
+ ## Current Focus
4
+
5
+ - Make Structor contribution work easier to route, bound, and validate.
6
+ - Preserve the distinction between Structor as a toolkit and harness engineering
7
+ as the practice.
8
+ - Keep the future one-command contributor bootstrap behind the quality of this
9
+ self-harness guidance.
10
+
11
+ ## Source Repo
12
+
13
+ - `../structor/package.json` owns CLI scripts and local validation commands.
14
+ - `../structor/bin/structor.mjs` owns the public CLI surface.
15
+ - `../structor/scripts/init-harness.mjs` renders generated harnesses from
16
+ configuration and templates.
17
+ - `../structor/scripts/lib.mjs` owns config resolution and path safety.
18
+ - `../structor/template/**` is the active generic generated-harness surface.
19
+ - `../structor/contrib/self-harness/**` owns this self-harness preset and
20
+ Structor-specific generated guidance.
21
+
22
+ ## Boundaries
23
+
24
+ - Structor scaffolds harness repositories; it does not run agents.
25
+ - Structor must not poll sessions, automate pull requests, auto-merge, mutate
26
+ GitHub, or become a runner.
27
+ - Active templates must stay generic for consumer projects.
28
+ - Model overlays and consumer entrypoints stay thin and route to canonical
29
+ harness policy.
30
+ - Source-repo pointer files should be previewed and skipped when they already
31
+ exist unless an explicit force path is used.
32
+
33
+ ## Validation Defaults
34
+
35
+ - In `../structor`, run `npm run validate` for the full local gate.
36
+ - For focused generator changes, also run the relevant `npm test` coverage.
37
+ - In this self-harness, run `node scripts/validate-governance.mjs`.
38
+ - After setup or pointer changes, run `node scripts/check-workspace.mjs`.
@@ -0,0 +1,72 @@
1
+ #!/usr/bin/env node
2
+
3
+ import { access, readFile } from "node:fs/promises";
4
+ import { constants as fsConstants } from "node:fs";
5
+ import path from "node:path";
6
+ import { fileURLToPath } from "node:url";
7
+
8
+ const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
9
+ const workspaceRoot = path.resolve(repoRoot, "..");
10
+ const sourceRoot = path.join(workspaceRoot, "structor");
11
+ const workspaceAgentPath = path.join(workspaceRoot, "AGENTS.md");
12
+ const requiredHarnessFiles = [
13
+ "AGENTS.md",
14
+ "ai/AGENTS.md",
15
+ "ai/HUB.md",
16
+ "ai/context.md",
17
+ "scripts/validate-governance.mjs",
18
+ ];
19
+
20
+ async function exists(filePath) {
21
+ try {
22
+ await access(filePath, fsConstants.F_OK);
23
+ return true;
24
+ } catch {
25
+ return false;
26
+ }
27
+ }
28
+
29
+ async function readIfExists(filePath) {
30
+ if (!(await exists(filePath))) return null;
31
+ return readFile(filePath, "utf8");
32
+ }
33
+
34
+ const errors = [];
35
+ if (path.basename(repoRoot) !== "structor-self") {
36
+ errors.push(`repo folder name: expected structor-self, found ${path.basename(repoRoot)}`);
37
+ }
38
+
39
+ for (const relativePath of requiredHarnessFiles) {
40
+ if (!(await exists(path.join(repoRoot, relativePath)))) {
41
+ errors.push(`missing self-harness file ${relativePath}`);
42
+ }
43
+ }
44
+
45
+ if (!(await exists(sourceRoot))) {
46
+ errors.push(`missing Structor source repo at ${sourceRoot}`);
47
+ }
48
+
49
+ const workspaceAgent = await readIfExists(workspaceAgentPath);
50
+ if (workspaceAgent === null) {
51
+ errors.push(`missing workspace entrypoint ${workspaceAgentPath}`);
52
+ } else if (!workspaceAgent.includes("structor-self")) {
53
+ errors.push(`workspace entrypoint ${workspaceAgentPath} must route to structor-self`);
54
+ }
55
+
56
+ const sourceAgentPath = path.join(sourceRoot, "AGENTS.md");
57
+ const sourceAgent = await readIfExists(sourceAgentPath);
58
+ if (sourceAgent === null) {
59
+ errors.push(`missing source entrypoint ${sourceAgentPath}`);
60
+ } else if (sourceAgent.includes("structor-self")) {
61
+ console.log("Source AGENTS.md routes to structor-self.");
62
+ } else {
63
+ console.log("Source AGENTS.md exists and was preserved; run setup with --force after review to replace it.");
64
+ }
65
+
66
+ if (errors.length > 0) {
67
+ console.error("Structor self-harness workspace check failed.");
68
+ for (const error of errors) console.error(`- ${error}`);
69
+ process.exit(1);
70
+ }
71
+
72
+ console.log("Structor self-harness workspace check passed.");
@@ -0,0 +1,37 @@
1
+ {
2
+ "$schema": "../../schemas/harness-config.schema.json",
3
+ "project": {
4
+ "name": "Structor Self-Harness",
5
+ "slug": "structor-self",
6
+ "harnessRepoName": "structor-self"
7
+ },
8
+ "output": {
9
+ "path": "./structor-self"
10
+ },
11
+ "models": {
12
+ "openai": true,
13
+ "anthropic": false
14
+ },
15
+ "clientSupport": {
16
+ "codex": {
17
+ "hooks": true
18
+ },
19
+ "claude": {
20
+ "rules": false,
21
+ "hooks": false,
22
+ "skills": false
23
+ }
24
+ },
25
+ "consumers": [
26
+ {
27
+ "name": "structor",
28
+ "path": "./structor",
29
+ "purpose": "Structor source repository: the generator, templates, schemas, docs, tests, and CLI for repository-local AI engineering harnesses.",
30
+ "validation": {
31
+ "install": "npm install",
32
+ "test": "npm test",
33
+ "health": "npm run validate"
34
+ }
35
+ }
36
+ ]
37
+ }
@@ -0,0 +1,45 @@
1
+ # Structor Contributor Setup
2
+
3
+ The manual contributor setup path is for people who already cloned Structor and
4
+ want the local self-harness without the future contributor bootstrap.
5
+
6
+ ```sh
7
+ git clone https://github.com/nicolaycamacho/structor.git
8
+ cd structor
9
+ npm run setup:contributor -- --dry-run
10
+ npm run setup:contributor
11
+ ```
12
+
13
+ The command generates or refreshes a sibling self-harness:
14
+
15
+ ```text
16
+ workspace/
17
+ structor/ # source repo contributors edit
18
+ structor-self/ # generated Structor Self-Harness
19
+ ```
20
+
21
+ ## Safety Model
22
+
23
+ - The preset source lives in `contrib/self-harness/**`.
24
+ - Generated Structor-specific guidance is written to the sibling
25
+ `structor-self` harness, not to active generic templates.
26
+ - The source repo is treated as the self-harness consumer repo.
27
+ - Source-repo pointer files are previewed before writes.
28
+ - Existing source `AGENTS.md`, `CLAUDE.md`, or other contributor entrypoints are
29
+ skipped unless `--force` is passed.
30
+ - The manual path does not clone repositories, require GitHub authentication,
31
+ push branches, open pull requests, or mutate external services.
32
+
33
+ ## Validation
34
+
35
+ After setup:
36
+
37
+ ```sh
38
+ npm run validate
39
+ cd ../structor-self
40
+ node scripts/validate-governance.mjs
41
+ node scripts/check-workspace.mjs
42
+ ```
43
+
44
+ Use `--force` only after reviewing the preview and deciding to replace existing
45
+ source-repo pointer files.
package/docs/INIT.md CHANGED
@@ -1,8 +1,10 @@
1
1
  # Structor Init
2
2
 
3
3
  `structor init` is the recommended first-run setup flow for a project workspace.
4
- It is a local-only, deterministic terminal wizard. It does not call an LLM, make
5
- API requests, install packages, create remotes, or modify external services.
4
+ It is a local-only, deterministic terminal wizard for creating a
5
+ repository-local AI engineering harness. It does not call an LLM, make API
6
+ requests, install packages, create remotes, run agents, or modify external
7
+ services.
6
8
 
7
9
  ## Recommended Command
8
10
 
@@ -21,6 +23,29 @@ During local development from this repo, use:
21
23
  npm run init -- --workspace ..
22
24
  ```
23
25
 
26
+ The current CLI supports `init`, `generate`, and `doctor`. It does not include a
27
+ runner command.
28
+
29
+ ## First Successful Local Path
30
+
31
+ The default first-run path is:
32
+
33
+ 1. Run `npx @structor-dev/cli init` from the parent workspace folder.
34
+ 2. Confirm the workspace, project name, generated harness path, agent clients,
35
+ and consumer repos.
36
+ 3. Let Structor write `harness.config.json` only after reviewing the summary.
37
+ 4. Review the dry-run preview of generated harness and consumer pointer files.
38
+ 5. Confirm generation only if the preview is correct.
39
+ 6. Run the next validation commands printed by the CLI.
40
+
41
+ During development from this repository, the equivalent local command is
42
+ `npm run init -- --workspace ..`.
43
+
44
+ This path creates a sibling generated harness repo with canonical `ai/*`
45
+ policy, thin Codex and Claude entrypoints, contracts, task templates, review
46
+ guidance, and local validation scripts. It does not create a runner or hosted
47
+ service; generated files remain local until you review and commit them.
48
+
24
49
  ## What It Reads
25
50
 
26
51
  - The current workspace folder, or the folder passed with `--workspace`.
@@ -42,6 +67,10 @@ Only after confirmation, it can write:
42
67
  Existing generated harness files and consumer entrypoints are skipped by the
43
68
  underlying generator unless the user passes `--force`.
44
69
 
70
+ Consumer entrypoints are thin pointer files. They route Codex and Claude Code
71
+ back to the generated harness; they are not copies of the canonical harness
72
+ policy.
73
+
45
74
  ## What It Never Does
46
75
 
47
76
  - No network calls.
@@ -52,6 +81,10 @@ underlying generator unless the user passes `--force`.
52
81
  - No runner behavior such as polling, auto-repair loops, dashboards, or
53
82
  auto-merge.
54
83
 
84
+ If setup discovers a missing behavior or incorrect wizard behavior, track that
85
+ as a separate CLI issue instead of changing templates or generated behavior as
86
+ part of documentation work.
87
+
55
88
  ## Workspace Detection
56
89
 
57
90
  Structor works best when run from a parent workspace folder:
@@ -90,6 +123,10 @@ implementation.
90
123
  - Codex and Claude support flags
91
124
  - consumer repo paths, purposes, and validation commands
92
125
 
126
+ Consumer repo paths are workspace-relative. The generator rejects absolute
127
+ consumer paths, `..` traversal, symlinked consumer paths, and entrypoint writes
128
+ to directories that do not look like repositories.
129
+
93
130
  `structor generate --config harness.config.json` uses this file to render the
94
131
  generated harness deterministically.
95
132
 
@@ -107,3 +144,19 @@ does not infer real project contracts, coding conventions, or architecture from
107
144
  consumer repo code.
108
145
 
109
146
  `Light scan` and `Deep scan` are reserved for future opt-in features.
147
+
148
+ ## Validation Split
149
+
150
+ Use the Structor package scripts from `package.json`:
151
+
152
+ ```sh
153
+ npm run check:ci
154
+ npm run validate
155
+ ```
156
+
157
+ `npm run check:ci` runs the fast structural checks used for local iteration and
158
+ CI hygiene.
159
+
160
+ `npm run validate` runs `check:ci`, the Node test suite, and the smoke-tested
161
+ initialization flow that generates disposable harnesses and verifies generated
162
+ governance and workspace routing.
@@ -0,0 +1,150 @@
1
+ # Public Launch Positioning
2
+
3
+ This is planning material for future external website and article work. It is
4
+ not polished marketing copy, not a landing page implementation, and not a
5
+ commitment to hosted services, analytics, forms, deployment, commercial assets
6
+ inside the open-source core, private policy packs, private templates, or
7
+ client-specific deliverables.
8
+
9
+ Structor should be presented as a local, open-source harness-engineering
10
+ toolkit. It generates repository-local AI engineering harnesses for consumer
11
+ repositories so coding agents share a consistent policy layer for context
12
+ routing, contracts, task shape, review, and validation.
13
+
14
+ ## Approved Positioning
15
+
16
+ - Structor generates a repository-local AI engineering harness for your
17
+ project.
18
+ - Structor is a generator, not a runtime.
19
+ - Structor scaffolds the harness; it does not run agents, poll sessions,
20
+ automate pull requests, auto-merge changes, or touch external services.
21
+ - The open-source generator is local-only: no telemetry, no LLM calls, and no
22
+ network calls during `init` or `generate`.
23
+ - Structor is MIT-licensed so teams can generate, modify, and use harness
24
+ artifacts inside private or commercial repositories.
25
+ - Reliable agentic engineering needs more than prompts. It needs context
26
+ architecture plus mechanical enforcement.
27
+
28
+ ## Audience Split
29
+
30
+ ### Individual Developers
31
+
32
+ Individual developers should understand Structor as a way to stop rebuilding
33
+ agent instructions from scratch in every repo. The promise is practical and
34
+ local: generate a repo-shaped harness, keep Codex and Claude guidance
35
+ consistent, and use validation to catch policy drift before it becomes review
36
+ noise.
37
+
38
+ The right tone is direct and tool-focused. Avoid implying that Structor replaces
39
+ the developer's judgment, runs the agent, hosts an agent workspace, or manages
40
+ pull requests.
41
+
42
+ ### Teams And Companies
43
+
44
+ Teams should understand Structor as a reusable harness layer for private and
45
+ commercial codebases. The open-source core can generate and validate local
46
+ harness artifacts that teams own in their repositories. This is useful when
47
+ multiple agents, models, or contributors need the same contracts, review shape,
48
+ and safety boundaries.
49
+
50
+ The right tone is operational and evidence-based. Emphasize repository-local
51
+ policy, deterministic generation, explicit write previews, validation scripts,
52
+ and MIT-licensed use in private repositories. Avoid implying hosted dashboards,
53
+ telemetry, managed agent execution, deployment checks, forms, analytics, or
54
+ private commercial assets bundled into the open-source core.
55
+
56
+ ### Future Commercial Support
57
+
58
+ Future commercial support can be described as separate from the OSS generator.
59
+ Possible paid offerings may include tailored rollout support, commercial policy
60
+ packs, private templates, training, audits, or hosted services, but those should
61
+ be framed as future or separately licensed work.
62
+
63
+ The public launch should not imply that these offerings already exist, are
64
+ included in the current package, or are required to use Structor. The OSS core
65
+ should remain understandable and valuable on its own.
66
+
67
+ ## Future Landing Page Outline
68
+
69
+ 1. Hero
70
+ - Headline: Structor
71
+ - Supporting copy: Generate repository-local AI engineering harnesses for
72
+ coding agents.
73
+ - Boundary note: A generator, not a runner.
74
+ 2. Problem
75
+ - Agent workflows often rely on scattered prompts, local conventions, and
76
+ review memory.
77
+ - Without a harness, guidance drifts across repos, models, and contributors.
78
+ 3. Product
79
+ - Structor creates a generated harness repo beside the consumer repositories.
80
+ - The harness owns agent guidance, contracts, review templates, validation,
81
+ and model-specific entrypoints.
82
+ 4. Local Safety Model
83
+ - `init` and `generate` are deterministic and local-only.
84
+ - No telemetry, no LLM calls, no network calls, and no external service
85
+ mutation during generation.
86
+ 5. Harness, Not Runner
87
+ - Structor does not execute agents, monitor sessions, open pull requests,
88
+ auto-merge, deploy, or manage production systems.
89
+ - Runner or orchestration behavior belongs in a separate layer.
90
+ 6. For Individuals
91
+ - Make one repo's agent guidance easier to start, inspect, and validate.
92
+ 7. For Teams
93
+ - Share a consistent local policy layer across models, contributors, and
94
+ private repositories.
95
+ 8. Open Source Core
96
+ - MIT-licensed generator.
97
+ - Local artifacts that users can inspect, commit, modify, or remove.
98
+ 9. Future Support
99
+ - Separately licensed support, policy packs, private templates, audits, or
100
+ hosted services may be explored later.
101
+ - Keep this section clearly separate from current OSS behavior.
102
+ 10. Next Step
103
+ - Point readers to the README and `docs/INIT.md` for the current local setup
104
+ flow.
105
+
106
+ ## Article Outline
107
+
108
+ Working title: "Your AI coding agents need a harness, not just prompts."
109
+
110
+ 1. The prompt pile problem
111
+ - Most teams start with instructions scattered across READMEs, local notes,
112
+ model-specific files, and review comments.
113
+ - The result is inconsistent context, unclear task shape, and repeated review
114
+ corrections.
115
+ 2. What a harness adds
116
+ - A harness gives agents a repository-local policy layer.
117
+ - It records contracts, routing, validation, task shape, and review
118
+ expectations as files that can be inspected and versioned.
119
+ 3. Why local matters
120
+ - Teams need to understand what the tool reads and writes.
121
+ - Local deterministic generation is easier to review than remote automation
122
+ or hidden runtime behavior.
123
+ 4. Why validation matters
124
+ - Policy files drift.
125
+ - Mechanical checks make the harness more than a folder of advice.
126
+ 5. Harness is not runner
127
+ - A harness shapes work; it does not execute the work.
128
+ - Running agents, polling sessions, PR automation, deployment, and hosted
129
+ workflows belong in separate systems.
130
+ 6. Where Structor fits
131
+ - Structor generates the local harness structure and starter policy for a
132
+ consumer workspace.
133
+ - The generated harness can support Codex, Claude Code, contracts, review
134
+ templates, and validation without taking over the user's repository.
135
+ 7. What comes later
136
+ - Future website material can discuss support, commercial policy packs,
137
+ private templates, training, audits, or hosted services only as separate
138
+ work.
139
+ - Keep the open-source generator's current behavior precise.
140
+
141
+ ## Language To Avoid
142
+
143
+ - Do not say Structor runs agents, supervises agents, manages sessions, opens
144
+ pull requests, auto-merges, deploys, or repairs repositories.
145
+ - Do not imply current hosted services, telemetry, analytics, forms, dashboards,
146
+ private policy packs, private templates, or client-specific assets.
147
+ - Do not frame commercial support as part of the open-source package.
148
+ - Do not describe the generated harness as a production runtime or CI system.
149
+ - Do not replace the harness-engineering story with generic AI productivity
150
+ claims.