UNPKG

aiwg

Version:

Deployment tool and support utility for AI context. Copies agents, skills, commands, rules, and behaviors into the paths each AI platform reads (Claude Code, Codex, Copilot, Cursor, Warp, OpenClaw, and 6 more) so one source of truth works across 10 platfo

aiwg.io

jmagly/aiwg

117 lines (68 loc) • 5.01 kB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
--- name: installer-safety description: Mandatory safety behaviors for the installer-agent and setup-run skill. Prevents destructive actions, enforces user authorization, and protects against script injection. type: feedback priority: HIGH --- # Installer Safety Rules Mandatory behaviors for all agents and skills operating on `setup.aiwg.io/v1` manifests. ## Rule 1: Show Before Run **Never execute a script without first showing the user what it will do.** Before running any `script` or `platform-route` step, print: - The script path - The environment variables (params) being passed - The `verify` expression, if present For `type: agentic` steps, additionally show the `instruction` field and explain what actions the agent intends to take. **Why:** Users must be able to audit every command before it executes on their system. **How to apply:** Every step execution must log header output before invoking the script. --- ## Rule 2: Confirm Destructive Operations **Never run destructive scripts without explicit user confirmation.** Destructive scripts include (but are not limited to): - `reset.sh` or any script containing `rm -rf` - Any `recovery_procedure` step - Scripts that overwrite existing files (check for `cp -f`, `mv`, truncation) Show the destructive action, the affected path(s), and wait for `[y/N]` confirmation. **Why:** Recovery scripts like `reset.sh` delete entire directories. Silent execution would destroy user data. **How to apply:** Before executing any recovery procedure or script that matches destructive patterns, prompt explicitly. Default answer is N. --- ## Rule 3: Validate Schema Before Execution **Never run a manifest that fails schema validation.** Always invoke `setup-validate` internally before `setup-run` executes the first step. If validation returns errors, stop and report them. Do not execute partial manifests. **Why:** A malformed manifest can produce inconsistent state — some steps executed, some skipped — that is harder to recover from than a clean failure. **How to apply:** `setup-run` must call the validation logic at Phase 1, before platform detection or param collection. --- ## Rule 4: Agentic Steps Are Exception Handling Only **Do not generate `type: agentic` steps for operations that can be scripted.** When generating a manifest (`setup-generate`), only emit `type: agentic` steps when: - The operation cannot be expressed in bash/PowerShell without runtime AI reasoning - A prior script step has already failed and the agentic step is the recovery path When executing a manifest (`setup-run`), if an `agentic` step is encountered: 1. Explain to the user why this step requires AI intervention 2. Show the `instruction` field 3. Describe the actions you intend to take before taking them **Why:** Agentic steps are non-reproducible and cannot be audited like scripts. Over-use erodes trust in the installer. **How to apply:** In `setup-generate`, prefer `script` for every step. Flag any `type: agentic` in `setup-validate` output with a warning. --- ## Rule 5: Params Collected Before Execution **All required params must be collected before any step runs.** Before executing step 1, collect all `required: true` params that have no value. Do not proceed with missing required params even if early steps do not use them — later steps may depend on them and partial execution creates hard-to-clean state. **Why:** Running 3 of 5 steps before discovering a missing param leaves the system in a partially-installed state. **How to apply:** During Phase 3 (Param Collection in setup-run), collect ALL required params upfront, not lazily per step. --- ## Rule 6: No Inline Secrets **Never put secrets, tokens, or passwords in a setup.manifest.yaml or in script templates.** If a script requires a secret: 1. Read it from a file (`~/.config/<project>/token`) 2. Read it from an environment variable 3. Prompt the user interactively (never echo to terminal) The manifest param system supports `type: string` params — these are for configuration values, not secrets. **Why:** Manifests are committed to source control. Secrets in manifests leak to every person with repo access. **How to apply:** When generating manifests, if a secret is needed, emit an `ask` step that reads from a file or prompts without echoing. Never use `default:` for secret values. --- ## Rule 7: Platform Mismatches Are Skip, Not Error **When a step's platform filter does not match the current system, skip it silently.** Steps filtered for `platform: [macos]` should produce no output on Ubuntu. The step did not fail — it was not applicable. Recovery procedures triggered on skipped steps are also skipped. **Why:** Cross-platform manifests routinely include platform-specific steps. Reporting them as errors on non-target platforms creates false failures. **How to apply:** In `setup-run` step dispatch, evaluate platform match before executing. Log `[skip: platform mismatch]` at debug verbosity only.