gabbe-kit 1.0.3 → 1.1.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.
- package/README.md +21 -0
- package/agents/AGENTS.md +36 -3
- package/agents/CONSTITUTION.md +1 -1
- package/agents/guides/00-index.md +4 -4
- package/agents/guides/ai/agent-only-cognition.md +10 -2
- package/agents/guides/ai/agent-only-swarms.md +4 -4
- package/agents/guides/ai/agent-operating-ergonomics.md +1 -1
- package/agents/guides/ai/ai-agentic.md +2 -4
- package/agents/guides/ai/beyond-llms.md +12 -2
- package/agents/guides/ai/multi-agent-systems.md +1 -1
- package/agents/guides/architecture/api-standards.md +9 -7
- package/agents/guides/architecture/critical-systems-arch.md +10 -4
- package/agents/guides/architecture/microservices.md +2 -2
- package/agents/guides/architecture/orchestration.md +3 -3
- package/agents/guides/architecture/systems-architecture.md +6 -0
- package/agents/guides/ops/cost-optimization.md +1 -1
- package/agents/guides/patterns/agentic-patterns.md +12 -40
- package/agents/guides/patterns/ai-native-scenarios.md +4 -4
- package/agents/guides/patterns/design-patterns.md +11 -65
- package/agents/guides/patterns/software-design-patterns.md +4 -2
- package/agents/guides/principles/clean-code-standards.md +1 -1
- package/agents/guides/principles/evaluation-strategy.md +18 -13
- package/agents/guides/principles/future-tech.md +1 -1
- package/agents/guides/principles/human-agent-collaboration.md +4 -3
- package/agents/guides/principles/legacy-tech.md +7 -3
- package/agents/guides/principles/testing-strategy.md +5 -3
- package/agents/guides/processes/loki-sdlc-phases.md +1 -1
- package/agents/guides/security/api-security.md +1 -1
- package/agents/guides/security/cryptography-standards.md +8 -2
- package/agents/guides/security/privacy-data-protection.md +2 -2
- package/agents/guides/security/secure-architecture.md +1 -1
- package/agents/skills/00-index.md +16 -16
- package/agents/skills/brain/active-inference.skill.md +1 -1
- package/agents/skills/brain/brain-mode.skill.md +9 -2
- package/agents/skills/brain/cost-benefit-router.skill.md +20 -8
- package/agents/skills/brain/loki-mode.skill.md +13 -10
- package/agents/skills/brain/sequential-thinking.skill.md +1 -1
- package/agents/skills/coding/mobile-dev.skill.md +1 -0
- package/agents/skills/coding/secure-coding.skill.md +1 -1
- package/agents/skills/coding/tdd-cycle.skill.md +1 -1
- package/agents/skills/coding/testing-strategy.skill.md +1 -1
- package/agents/skills/coding/visual-design.skill.md +1 -0
- package/agents/skills/coordination/agent-interop.skill.md +5 -4
- package/agents/skills/coordination/meta-optimize.skill.md +2 -2
- package/agents/skills/coordination/multi-agent-orch.skill.md +1 -1
- package/agents/skills/coordination/persona-selector.skill.md +1 -1
- package/agents/skills/coordination/self-optimize.skill.md +1 -1
- package/agents/skills/coordination/swarm-consensus.skill.md +10 -0
- package/agents/skills/core/audit-trail.skill.md +1 -1
- package/agents/skills/core/emerging-tech.skill.md +1 -1
- package/agents/skills/core/integrity-check.skill.md +1 -1
- package/agents/skills/core/knowledge-connect.skill.md +1 -0
- package/agents/skills/core/preflight.skill.md +8 -0
- package/agents/skills/core/sdlc-checkpoint.skill.md +7 -2
- package/agents/skills/core/self-heal.skill.md +17 -4
- package/agents/skills/core/session-resume.skill.md +8 -3
- package/agents/skills/core/state-portability.skill.md +3 -2
- package/agents/skills/ops/incident-response.skill.md +1 -0
- package/agents/skills/ops/production-health.skill.md +1 -0
- package/agents/skills/ops/release-management.skill.md +1 -0
- package/agents/skills/ops/system-benchmark.skill.md +1 -0
- package/agents/skills/product/spec-writer.skill.md +6 -3
- package/agents/skills/security/ai-safety-guardrails.skill.md +15 -6
- package/agents/skills/security/legal-review.skill.md +1 -0
- package/agents/skills/security/reliability-engineering.skill.md +4 -3
- package/agents/templates/coding/CLEAN_CODE_CHECKLIST.md +1 -1
- package/agents/templates/coding/EVAL_RUBRIC_TEMPLATE.md +7 -0
- package/agents/templates/coding/GOLDEN_DATASET_TEMPLATE.md +1 -1
- package/agents/templates/coding/TEST_PLAN_TEMPLATE.md +2 -2
- package/agents/templates/coordination/AGENTS_TEMPLATE.md +133 -16
- package/agents/templates/core/AUDIT_LOG_TEMPLATE.md +1 -1
- package/agents/templates/core/SESSION_SNAPSHOT_TEMPLATE.md +3 -3
- package/agents/templates/ops/TECH_DEBT_TEMPLATE.md +1 -1
- package/agents/templates/product/PRD_TEMPLATE.md +8 -2
- package/agents/templates/product/SPEC_TEMPLATE.md +9 -3
- package/agents/templates/product/VISUAL_SPEC_PACKAGE_TEMPLATE.md +1 -1
- package/bin/install.js +36 -6
- package/docs/CLI_REFERENCE.md +43 -5
- package/docs/INSTALL.md +23 -10
- package/docs/adr/0002-brain-active-inference-runtime.md +29 -8
- package/package.json +2 -2
- package/scripts/init.py +488 -8
|
@@ -160,9 +160,38 @@ Import style:
|
|
|
160
160
|
|
|
161
161
|
## 5. Workflow for Agents — Review-Driven Development
|
|
162
162
|
|
|
163
|
-
Agents MUST follow this order
|
|
163
|
+
Agents MUST follow this order; skipping steps is forbidden. Keep `agents/memory/` current at
|
|
164
|
+
every task (episodic, semantic, AUDIT_LOG, CONTINUITY, PROJECT_STATE, RESUME_POINTER), and consult
|
|
165
|
+
`agents/{skills,guides,templates}/` for relevant capabilities at each step.
|
|
166
|
+
|
|
167
|
+
**CRITICAL MANDATES (always apply):**
|
|
168
|
+
|
|
169
|
+
- **Optimal skill/guide/MCP selection** — analyze the task and select (or ask the user to confirm) the best skills/guides/templates; never default to generic execution when a specialized one exists. Recommend enabling any MCP server that would materially help.
|
|
170
|
+
- **Cost & budget by default** — minimize tokens/context/API cost; never use swarms or SOTA models for simple work, and **ask the human before any expensive/SOTA/high-cost approach** (with a one-line cost-benefit). Four levers (`guides/ops/cost-optimization.md`): prompt caching (stable context first), context budgeting (load minimum, prefer `context_cost: low`), model tiering (`gabbe route`), batching. Never weaken the gates, the SDLC phases, or HITL to save cost.
|
|
171
|
+
- **Spec-driven (first-class)** — `spec → evals → test → code`, never code-first. Non-trivial features start from an **EARS** spec (`product/spec-writer.skill`, `templates/product/SPEC_TEMPLATE.md`, `guides/planning/product-requirements.md`); keep a **golden thread** (requirement → spec → test → code → audit). No requirement without a test (Article I); resolve ambiguity in the spec via `clarify.skill`.
|
|
172
|
+
- **Observability (first-class)** — every run/decision/model+tool call is traced with token usage + **per-step cost attribution** (`core/audit-trail.skill`, `core/agent-analytics.skill`; OTel GenAI conventions `gen_ai.usage.*`; span tree root→plan→discover→execute→retrieve). Redact content by default (Article IV); `AUDIT_LOG.md` is authoritative without the CLI.
|
|
173
|
+
- **Human–agent collaboration (manager, not operator)** — the human delegates → observes → intervenes on exceptions. Keep three questions always answerable: **Purpose** (scope/non-goals via spec), **Transparency** (legible reasoning/tools/cost via observability), **Control** (pause/correct/approve via HITL). Prefer an async, observable surface; "done" only when all three hold (`guides/principles/human-agent-collaboration.md`).
|
|
174
|
+
|
|
175
|
+
### Step 0 — Preflight & Clarify (before anything else)
|
|
176
|
+
|
|
177
|
+
```
|
|
178
|
+
Run preflight.skill as the FIRST action of every session and every major task:
|
|
179
|
+
1. Auto-checks: integrity-check (fast) → confirm memory + working tree are coherent.
|
|
180
|
+
2. Load index SUMMARIES (not bodies): agents/{skills,guides,templates,personas}/00-index.md
|
|
181
|
+
→ know what capabilities exist before choosing generically.
|
|
182
|
+
3. Load memory headers with decay-aware priming (PROJECT_STATE, CONTINUITY, latest snapshot).
|
|
183
|
+
4. Surface cost posture: GABBE_AUTONOMY (ask|auto|hybrid, default hybrid) + remaining budget.
|
|
184
|
+
5. Recommend the OPTIMAL set for the task (skills/guides/persona/MCP), ranked by
|
|
185
|
+
relevance × (1/context_cost); pick a reasoning pattern proportionate to task + budget.
|
|
186
|
+
6. Flag new/changed capabilities since last preflight (defer adoption to update-scan.skill).
|
|
187
|
+
7. End by invoking clarify.skill → ask the focused batch of clarifying questions
|
|
188
|
+
(and "questions you should ask me") before proceeding.
|
|
189
|
+
Do not begin implementation until blocking questions are answered, unless the autonomy
|
|
190
|
+
posture is `auto` AND the task is cheap AND reversible.
|
|
191
|
+
```
|
|
164
192
|
|
|
165
193
|
### Step 1 — Load Context (every session start)
|
|
194
|
+
|
|
166
195
|
```
|
|
167
196
|
1. Read this AGENTS.md completely
|
|
168
197
|
2. Read CONSTITUTION.md if it exists
|
|
@@ -172,6 +201,7 @@ Agents MUST follow this order. Skipping steps is forbidden.
|
|
|
172
201
|
```
|
|
173
202
|
|
|
174
203
|
### Step 2 — Plan Before Coding
|
|
204
|
+
|
|
175
205
|
```
|
|
176
206
|
Before touching any file, write a brief implementation plan:
|
|
177
207
|
- What files will you create or modify?
|
|
@@ -184,6 +214,7 @@ For complex tasks: write plan.md or use PLAN_TEMPLATE.md
|
|
|
184
214
|
```
|
|
185
215
|
|
|
186
216
|
### Step 3 — Test First (TDD Red Phase)
|
|
217
|
+
|
|
187
218
|
```
|
|
188
219
|
Write the failing test BEFORE writing implementation code.
|
|
189
220
|
Run the test -- it MUST fail (Red).
|
|
@@ -191,12 +222,14 @@ If the test passes immediately with no implementation: the test is WRONG. Fix it
|
|
|
191
222
|
```
|
|
192
223
|
|
|
193
224
|
### Step 4 — Implement (TDD Green Phase)
|
|
225
|
+
|
|
194
226
|
```
|
|
195
227
|
Write the minimal code to make the failing test pass.
|
|
196
228
|
Do not add features not covered by a failing test.
|
|
197
229
|
```
|
|
198
230
|
|
|
199
231
|
### Step 5 — Verify (must all pass before marking done)
|
|
232
|
+
|
|
200
233
|
```
|
|
201
234
|
Run: [test command] -> must pass
|
|
202
235
|
Run: [typecheck command] -> must pass
|
|
@@ -205,23 +238,36 @@ Run: agentic-linter check -> no boundary violations
|
|
|
205
238
|
```
|
|
206
239
|
|
|
207
240
|
### Step 6 — Refactor
|
|
241
|
+
|
|
208
242
|
```
|
|
209
243
|
Improve code quality while keeping all tests green.
|
|
210
244
|
Check: Cyclomatic complexity < 10, no code duplication > 3 occurrences, no dead code.
|
|
211
245
|
```
|
|
212
246
|
|
|
213
247
|
### Step 7 — Log & Complete
|
|
248
|
+
|
|
214
249
|
```
|
|
215
250
|
Write entry to agents/memory/AUDIT_LOG.md
|
|
216
251
|
Update task status in project/TASKS.md to DONE
|
|
252
|
+
Refresh agents/memory/RESUME_POINTER.md (state-preserve.skill) — keep the
|
|
253
|
+
"next action" current so any future session resumes losslessly
|
|
217
254
|
If this completes a SDLC phase: invoke sdlc-checkpoint.skill
|
|
218
255
|
```
|
|
219
256
|
|
|
257
|
+
> **State preservation is continuous, not just at Step 7.** Per `state-preserve.skill`
|
|
258
|
+
> and §13, save incrementally after every meaningful step and flush a full snapshot
|
|
259
|
+
> before budget/time runs out — assume a cutoff can happen at any moment.
|
|
260
|
+
|
|
220
261
|
---
|
|
221
262
|
|
|
222
263
|
## 6. Governance & Security
|
|
223
264
|
|
|
265
|
+
### 🛡️ Mandatory Security & Guardrails
|
|
266
|
+
|
|
267
|
+
Agents MUST adhere to the **Security & Guardrails** section appended to the bottom of whatever skill they are currently executing. Bypassing these skill-specific guardrails is strictly forbidden.
|
|
268
|
+
|
|
224
269
|
### Forbidden Actions (agents must never do these without explicit human approval)
|
|
270
|
+
|
|
225
271
|
```
|
|
226
272
|
- Commit .env files or any file containing secrets
|
|
227
273
|
- Push directly to main/master branch
|
|
@@ -236,6 +282,7 @@ If this completes a SDLC phase: invoke sdlc-checkpoint.skill
|
|
|
236
282
|
```
|
|
237
283
|
|
|
238
284
|
### Secrets Policy
|
|
285
|
+
|
|
239
286
|
```
|
|
240
287
|
All secrets MUST be in environment variables.
|
|
241
288
|
Local dev: .env file (always in .gitignore)
|
|
@@ -245,6 +292,7 @@ Use: [PLACEHOLDER: dotenv | .env.vault | AWS Secrets Manager | HashiCorp Vault]
|
|
|
245
292
|
```
|
|
246
293
|
|
|
247
294
|
### PR Format (Conventional Commits)
|
|
295
|
+
|
|
248
296
|
```
|
|
249
297
|
Format: <type>(<scope>): <subject>
|
|
250
298
|
|
|
@@ -266,10 +314,11 @@ PR body must include:
|
|
|
266
314
|
```
|
|
267
315
|
|
|
268
316
|
### Quality Gates (all must pass before PR merges)
|
|
317
|
+
|
|
269
318
|
```
|
|
270
319
|
Gate 1 -- Syntax/Linting: ESLint / PHP-CS-Fixer / Prettier / Ruff -- zero errors
|
|
271
320
|
Gate 2 -- Type Safety: tsc --noEmit / PHPStan L9 / mypy -- zero errors
|
|
272
|
-
Gate 3 -- Test Coverage:
|
|
321
|
+
Gate 3 -- Test Coverage: >= 99% coverage, all tests passing, no skipped tests
|
|
273
322
|
Gate 4 -- Integration: Docker Compose up, API contract validation
|
|
274
323
|
Gate 5 -- Security scan: npm audit / composer audit -- no critical or high CVEs
|
|
275
324
|
Gate 6 -- Complexity: Cyclomatic complexity < 10 on modified files
|
|
@@ -283,6 +332,7 @@ Gate 7 -- EARS Compliance: (for new features) All requirements have tests
|
|
|
283
332
|
Agents must use authoritative sources. Never guess or hallucinate.
|
|
284
333
|
|
|
285
334
|
### Source Tiers (in order of trust)
|
|
335
|
+
|
|
286
336
|
```
|
|
287
337
|
Tier 1 (Primary -- always prefer):
|
|
288
338
|
- Official language/framework docs (MDN, nodejs.org, laravel.com, docs.python.org)
|
|
@@ -303,6 +353,7 @@ NOT acceptable (never cite as authoritative):
|
|
|
303
353
|
```
|
|
304
354
|
|
|
305
355
|
### Research Gate -- mandatory before:
|
|
356
|
+
|
|
306
357
|
```
|
|
307
358
|
- Using any library not in existing package.json / composer.json
|
|
308
359
|
- Calling any API method not confirmed in official docs
|
|
@@ -311,6 +362,7 @@ NOT acceptable (never cite as authoritative):
|
|
|
311
362
|
```
|
|
312
363
|
|
|
313
364
|
### When to invoke research.skill
|
|
365
|
+
|
|
314
366
|
```
|
|
315
367
|
"I'm not sure about X" -> knowledge-gap.skill -> research.skill -> confirm before coding
|
|
316
368
|
If library version not found in official docs -> do NOT assume behavior -> report to human
|
|
@@ -324,6 +376,7 @@ Use Context-7 MCP for library docs (prevents hallucinated deprecated API usage)
|
|
|
324
376
|
Agents may autonomously fix failures up to 5 attempts.
|
|
325
377
|
|
|
326
378
|
### What agents may self-heal (no human approval needed):
|
|
379
|
+
|
|
327
380
|
```
|
|
328
381
|
- Type errors and lint errors
|
|
329
382
|
- Test assertion updates when spec changed
|
|
@@ -334,6 +387,7 @@ Agents may autonomously fix failures up to 5 attempts.
|
|
|
334
387
|
```
|
|
335
388
|
|
|
336
389
|
### What requires human decision:
|
|
390
|
+
|
|
337
391
|
```
|
|
338
392
|
- Architecture or library changes
|
|
339
393
|
- Breaking API changes (any consumer affected)
|
|
@@ -345,7 +399,9 @@ Agents may autonomously fix failures up to 5 attempts.
|
|
|
345
399
|
```
|
|
346
400
|
|
|
347
401
|
### Self-Heal Escalation Protocol
|
|
402
|
+
|
|
348
403
|
After 5 failed attempts, agent MUST:
|
|
404
|
+
|
|
349
405
|
```
|
|
350
406
|
1. STOP all autonomous action
|
|
351
407
|
2. Create structured escalation report:
|
|
@@ -357,6 +413,15 @@ After 5 failed attempts, agent MUST:
|
|
|
357
413
|
4. Wait for human response before continuing
|
|
358
414
|
```
|
|
359
415
|
|
|
416
|
+
### Self-Evolving Policy (within cost + permission bounds)
|
|
417
|
+
|
|
418
|
+
The system may keep itself current and improve (new/better skills, tools, MCPs, models) via
|
|
419
|
+
`update-scan.skill` — but only inside hard bounds (full detail in that skill):
|
|
420
|
+
|
|
421
|
+
- **Allowed** (gated by `GABBE_AUTONOMY` + budget): adopt a cheaper/better reversible+validated tool/model; import a vetted external skill (validated first); refine prompts/personas from **successful** trajectories only.
|
|
422
|
+
- **Always needs human approval** (even under `auto`): anything expensive/SOTA/irreversible, externally-sourced runnable code, or any change to protected files.
|
|
423
|
+
- **Guardrails:** misaligned-replay guard (never learn from failed runs); protected files (never auto-edit build/IaC/CI/dependency manifests outside the self-heal allowlist); policy-as-code self-enforcement with every adoption/rejection logged to `AUDIT_LOG.md`; prefer canary + rollback, version evolved components.
|
|
424
|
+
|
|
360
425
|
---
|
|
361
426
|
|
|
362
427
|
## 9. Human-in-the-Loop Triggers
|
|
@@ -373,6 +438,8 @@ ALWAYS pause and ask:
|
|
|
373
438
|
- Architectural change (new service, new database, library switch)
|
|
374
439
|
- Any discovered vulnerability that requires feature disablement
|
|
375
440
|
- "I've tried 5 times and cannot fix this" (see Self-Healing Policy)
|
|
441
|
+
- Any expensive / SOTA-model / irreversible action — even under GABBE_AUTONOMY=auto
|
|
442
|
+
- Adopting a new tool, model, or externally-sourced skill (see update-scan / skills-registry)
|
|
376
443
|
- [PLACEHOLDER: add project-specific escalation triggers]
|
|
377
444
|
|
|
378
445
|
Format for human escalation:
|
|
@@ -385,11 +452,20 @@ Format for human escalation:
|
|
|
385
452
|
Awaiting: [specific decision needed]
|
|
386
453
|
```
|
|
387
454
|
|
|
455
|
+
**Clarify at every major step (not just at session start).** Per `clarify.skill`, the agent
|
|
456
|
+
estimates its own uncertainty before each major step and asks a focused batch of clarifying
|
|
457
|
+
questions (≈3–6, highest-impact first) whenever interpretation is ambiguous, a decision input is
|
|
458
|
+
missing, retrieval/verification failed, or the action is expensive/irreversible. The amount of
|
|
459
|
+
questioning scales with the `GABBE_AUTONOMY` posture (ask → clarify freely; hybrid → clarify on
|
|
460
|
+
real ambiguity; auto → silent for cheap/reversible work but always pause for the cases above).
|
|
461
|
+
Record assumed defaults in `agents/memory/AUDIT_LOG.md` so silence is informed, not a guess.
|
|
462
|
+
|
|
388
463
|
---
|
|
389
464
|
|
|
390
465
|
## 10. Tool-Specific Overrides
|
|
391
466
|
|
|
392
467
|
### Claude Code (claude.ai/code, Claude Code CLI)
|
|
468
|
+
|
|
393
469
|
```
|
|
394
470
|
- Skills: Use slash commands matching skill names (e.g., /tdd-cycle, /code-review)
|
|
395
471
|
- Memory: Use TodoWrite tool for task tracking
|
|
@@ -398,6 +474,7 @@ Format for human escalation:
|
|
|
398
474
|
```
|
|
399
475
|
|
|
400
476
|
### Cursor
|
|
477
|
+
|
|
401
478
|
```
|
|
402
479
|
- Context: This AGENTS.md is symlinked to .cursorrules
|
|
403
480
|
- Skills: Reference skill files directly in conversation
|
|
@@ -405,12 +482,14 @@ Format for human escalation:
|
|
|
405
482
|
```
|
|
406
483
|
|
|
407
484
|
### GitHub Copilot
|
|
485
|
+
|
|
408
486
|
```
|
|
409
487
|
- Context: Instructions from .github/copilot-instructions.md (symlinked)
|
|
410
488
|
- Skills: Reference skills/ directory files in comments or conversation
|
|
411
489
|
```
|
|
412
490
|
|
|
413
491
|
### Antigravity / Gemini CLI
|
|
492
|
+
|
|
414
493
|
```
|
|
415
494
|
- Context: This AGENTS.md is symlinked to .gemini/settings.json (instructions field)
|
|
416
495
|
- Skills: Symlinked to .agent/skills/ -- invoke by trigger keywords
|
|
@@ -442,7 +521,12 @@ Agent context priority: Package AGENTS.md > Root AGENTS.md
|
|
|
442
521
|
|
|
443
522
|
## 12. References
|
|
444
523
|
|
|
445
|
-
|
|
524
|
+
**Discover skills via the index — `agents/skills/00-index.md` is the canonical catalog**: native
|
|
525
|
+
skill menus (e.g. Claude Code) may truncate large collections by token budget, so always consult
|
|
526
|
+
the index to find any skill, then read its full file before use. Per-tool skill locations: see §10.
|
|
527
|
+
|
|
528
|
+
**Skill access (search first, read before use):**
|
|
529
|
+
|
|
446
530
|
- **Search First**: Before coding, search for relevant skills:
|
|
447
531
|
- **Cursor**: Check `.cursor/rules/` for `.mdc` files.
|
|
448
532
|
- **VS Code / Copilot**: Check `.github/skills/` or invoke via slash command.
|
|
@@ -452,16 +536,17 @@ Agent context priority: Package AGENTS.md > Root AGENTS.md
|
|
|
452
536
|
|
|
453
537
|
```
|
|
454
538
|
Project law: agents/CONSTITUTION.md
|
|
455
|
-
Skills
|
|
456
|
-
|
|
457
|
-
Orchestrators: agents/skills/brain/README.md
|
|
458
|
-
Brain Patterns: agents/skills/brain/README.md
|
|
539
|
+
Skills (canonical): agents/skills/00-index.md (master: agents/skills/**)
|
|
540
|
+
Guides: agents/guides/00-index.md
|
|
459
541
|
Templates: agents/templates/00-index.md
|
|
460
|
-
|
|
542
|
+
Personas (Loki): agents/personas/00-index.md
|
|
543
|
+
Brain patterns: agents/skills/brain/README.md
|
|
544
|
+
Quick reference: docs/QUICK_GUIDE.md
|
|
461
545
|
Project memory: agents/memory/PROJECT_STATE.md
|
|
462
546
|
Past failures: agents/memory/CONTINUITY.md
|
|
463
547
|
Decision log: agents/memory/AUDIT_LOG.md
|
|
464
548
|
```
|
|
549
|
+
|
|
465
550
|
- **Skills**: `agents/skills/` (Master) → `.cursor/rules/` (*.mdc) | `.github/skills/` | `.claude/skills/`
|
|
466
551
|
- **Memory**: `agents/memory/`
|
|
467
552
|
|
|
@@ -474,19 +559,33 @@ Every session, agents MUST:
|
|
|
474
559
|
```
|
|
475
560
|
START of session:
|
|
476
561
|
1. Read this AGENTS.md
|
|
477
|
-
2. Read agents/memory/
|
|
478
|
-
3. Read agents/memory/
|
|
479
|
-
4.
|
|
480
|
-
5.
|
|
481
|
-
6.
|
|
562
|
+
2. Read agents/memory/RESUME_POINTER.md (the lifeline — current task + NEXT ACTION)
|
|
563
|
+
3. Read agents/memory/PROJECT_STATE.md (if exists) -> understand current state
|
|
564
|
+
4. Read agents/memory/CONTINUITY.md (if exists) -> understand past failures
|
|
565
|
+
5. Load latest agents/memory/episodic/SESSION_SNAPSHOT/ (if exists)
|
|
566
|
+
6. If resuming: use session-resume.skill for full recovery
|
|
567
|
+
7. Run integrity-check.skill before starting new work on existing code
|
|
568
|
+
|
|
569
|
+
CONTINUOUSLY — never lose progress (state-preserve.skill; assume a cutoff at any moment):
|
|
570
|
+
- After each meaningful step: refresh RESUME_POINTER.md (current task + precise NEXT ACTION)
|
|
571
|
+
and append the outcome to AUDIT_LOG.md.
|
|
572
|
+
- Pre-exhaustion flush: when budget/tokens/turns run low or before a long/irreversible action,
|
|
573
|
+
write a FULL snapshot FIRST (RESUME_POINTER, then snapshot/PROJECT_STATE/CONTINUITY).
|
|
574
|
+
- On-disk Markdown memory must always suffice for a fresh agent to resume losslessly.
|
|
575
|
+
|
|
576
|
+
PORTABLE — switch coding agent or LLM anytime (state-portability.skill):
|
|
577
|
+
DEHYDRATE (state_export.sh → STATE_HANDOFF.md + a lossless bundle) and HYDRATE in the
|
|
578
|
+
destination agent (state_import.sh), then run session-resume + preflight. Memory + instructions
|
|
579
|
+
+ state are a fully compatible export/import. Never export secrets; merge (don't clobber) on import.
|
|
482
580
|
|
|
483
581
|
END of session:
|
|
484
582
|
1. Update project/TASKS.md with current status of all in-progress tasks
|
|
485
583
|
2. Write session summary to agents/memory/episodic/ (DECISION_LOG_TEMPLATE.md)
|
|
486
584
|
3. Update agents/memory/PROJECT_STATE.md with current SDLC phase
|
|
487
585
|
4. Write all decisions/outcomes to agents/memory/AUDIT_LOG.md
|
|
488
|
-
5.
|
|
489
|
-
6.
|
|
586
|
+
5. Update agents/memory/CONTINUITY.md with lessons learned
|
|
587
|
+
6. Create SDLC checkpoint if a phase was completed
|
|
588
|
+
7. If stopping mid-task: note exactly where you stopped and why (RESUME_POINTER)
|
|
490
589
|
```
|
|
491
590
|
|
|
492
591
|
---
|
|
@@ -535,6 +634,24 @@ Examples:
|
|
|
535
634
|
|
|
536
635
|
---
|
|
537
636
|
|
|
637
|
+
## Loki & Brain — Agentic Orchestration
|
|
638
|
+
|
|
639
|
+
Two optional orchestration modes (both run purely via Markdown inference; the `gabbe`
|
|
640
|
+
CLI is optional). Full definitions live in the skills — this is only a pointer (avoid
|
|
641
|
+
restating them here, to prevent drift):
|
|
642
|
+
|
|
643
|
+
- **🧠 Brain Mode** (`brain/brain-mode.skill.md`) — the Strategist (System 2): meta-cognitive
|
|
644
|
+
planner/router/optimizer (Active Inference framing + dynamic cost routing). Trigger: `gabbe brain activate`, `supermode`.
|
|
645
|
+
- **⚡ Loki Mode** (`brain/loki-mode.skill.md`) — the Executor (System 1): the deterministic
|
|
646
|
+
SDLC lifecycle (S00→S13, 14 phases) with human-in-the-loop hard gates at S00 (GO/NO-GO),
|
|
647
|
+
S01, S02, S07, S08. Trigger: `loki`, `orchestrate`.
|
|
648
|
+
|
|
649
|
+
Brain Mode **wraps** Loki: it receives the request, routes by complexity/budget, runs Loki for
|
|
650
|
+
the SDLC, and monitors — intervening if cost spikes, errors loop, or requirements drift. Both use
|
|
651
|
+
the same operating spine in §5/§13 (preflight → clarify → act → state-preserve → final-review).
|
|
652
|
+
|
|
653
|
+
---
|
|
654
|
+
|
|
538
655
|
*Last updated: [DATE]*
|
|
539
|
-
*GABBE Kit version: 1.0
|
|
656
|
+
*GABBE Kit version: 1.1.0*
|
|
540
657
|
*This file is maintained by the team and updated when project conventions change.*
|
|
@@ -65,7 +65,7 @@ EXAMPLE ENTRIES (remove this comment block when using):
|
|
|
65
65
|
| 2025-03-15T16:00:00Z | S05-001 | eng-backend | TASK_BLOCKED | T-020: Cannot implement payment integration — unclear if Stripe or Paddle | OPEN | project/TASKS.md |
|
|
66
66
|
| 2025-03-15T16:01:00Z | S05-001 | eng-backend | HUMAN_ESCALATION | T-020 blocked: Payment provider not decided. Options: Stripe (fees: 2.9%) vs Paddle (fees: 5%). Recommend Stripe (direct settlement). | ESCALATED | project/TASKS.md |
|
|
67
67
|
| 2025-03-15T16:45:00Z | S05-001 | human:bob | DECISION | Use Stripe for payment processing — direct settlement preferred | APPROVED | — |
|
|
68
|
-
| 2025-03-15T17:00:00Z | S06-001 | orch-judge | QUALITY_GATE | Gate 3 Tests: 247 pass, 0 fail, 0 skip,
|
|
68
|
+
| 2025-03-15T17:00:00Z | S06-001 | orch-judge | QUALITY_GATE | Gate 3 Tests: 247 pass, 0 fail, 0 skip, 99% coverage | PASS | — |
|
|
69
69
|
| 2025-03-15T17:05:00Z | S07-001 | ops-security | SECURITY_FINDING | HIGH: No rate limit on /auth/login endpoint — brute force possible | OPEN | src/adapters/http/auth.controller.ts:23 |
|
|
70
70
|
| 2025-03-15T17:30:00Z | S07-001 | eng-backend | TASK_DONE | Added rate limiting to /auth/login: 5 req/min per IP | SUCCESS | src/adapters/http/auth.controller.ts |
|
|
71
71
|
| 2025-03-15T17:31:00Z | S07-001 | ops-security | SECURITY_FINDING | HIGH: No rate limit on /auth/login — RESOLVED | RESOLVED | src/adapters/http/auth.controller.ts |
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
# Session Snapshot — S[XX]_[PHASE_NAME]
|
|
2
|
-
<!-- Created by: sdlc-checkpoint.skill -->
|
|
2
|
+
<!-- Created by: sdlc-checkpoint.skill (the SESSION_SNAPSHOT/ directory is created on first checkpoint) -->
|
|
3
3
|
<!-- Store in: agents/memory/episodic/SESSION_SNAPSHOT/S[XX]_[phase].md -->
|
|
4
4
|
<!-- IMMUTABLE after creation — never overwrite, create new snapshot for revisions -->
|
|
5
5
|
|
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
|
|
8
8
|
**Snapshot ID:** S[XX]-[YYYYMMDD]-[HH]
|
|
9
9
|
**Timestamp:** [ISO 8601: 2025-03-15T14:30:00Z]
|
|
10
|
-
**SDLC Phase:** S[XX] — [Phase Name: REQUIREMENTS/DESIGN/SPEC/TASKS/IMPLEMENTATION/TESTING/SECURITY/REVIEW/STAGING/PRODUCTION]
|
|
10
|
+
**SDLC Phase:** S[XX] — [Phase Name: DISCOVERY(S00)/REQUIREMENTS(S01)/DESIGN(S02)/SPEC(S03)/TASKS(S04)/IMPLEMENTATION(S05)/TESTING(S06)/SECURITY(S07)/REVIEW(S08)/STAGING(S09)/PRODUCTION(S10)/OPERATE(S11)/EVOLVE(S12)/DECOMMISSION(S13)]
|
|
11
11
|
**Created by:** [agent persona name or "human"]
|
|
12
12
|
**Project:** [Project name from AGENTS.md]
|
|
13
13
|
|
|
@@ -19,7 +19,7 @@
|
|
|
19
19
|
SDLC Phase: S[XX] — [Phase Name]
|
|
20
20
|
Phase status: COMPLETED / IN_PROGRESS
|
|
21
21
|
Gate criteria met: YES / NO (if NO, explain)
|
|
22
|
-
Overall progress: [X]/
|
|
22
|
+
Overall progress: [X]/14 phases complete (S00–S13)
|
|
23
23
|
Confidence: HIGH / MEDIUM / LOW
|
|
24
24
|
```
|
|
25
25
|
|
|
@@ -80,7 +80,7 @@ Example:
|
|
|
80
80
|
| Metric | Current | Target | Trend |
|
|
81
81
|
|---|---|---|---|
|
|
82
82
|
| Cyclomatic complexity (max) | [X] | < 10 | [improving/stable/worsening] |
|
|
83
|
-
| Test coverage | [X]% |
|
|
83
|
+
| Test coverage | [X]% | >= 99% | [improving/stable/worsening] |
|
|
84
84
|
| Code duplication | [X]% | < 3% | [improving/stable/worsening] |
|
|
85
85
|
| TODO/FIXME count | [X] | 0 untracked | [improving/stable/worsening] |
|
|
86
86
|
| Outdated major deps | [X] | 0 | [improving/stable/worsening] |
|
|
@@ -157,9 +157,15 @@ DELETE /api/v1/[resource]/{id} Delete
|
|
|
157
157
|
|
|
158
158
|
---
|
|
159
159
|
|
|
160
|
-
## 9. Non-Functional Requirements
|
|
160
|
+
## 9. Non-Functional Requirements (Summary)
|
|
161
161
|
|
|
162
|
-
|
|
162
|
+
<!-- This is a SUMMARY only. The authoritative, full NFR definition (RTO/RPO, latency
|
|
163
|
+
percentiles, throughput, encryption, observability, compatibility) lives in
|
|
164
|
+
NFR_TEMPLATE.md — link it here and do not duplicate detail. -->
|
|
165
|
+
|
|
166
|
+
**Full NFR definition:** [Link to NFR.md (from NFR_TEMPLATE.md)]
|
|
167
|
+
|
|
168
|
+
| Category | Headline target (full detail in NFR.md) |
|
|
163
169
|
|---|---|
|
|
164
170
|
| **Performance** | API responses < [X]ms at p99 under [Y] concurrent users |
|
|
165
171
|
| **Availability** | [X]% uptime SLO |
|
|
@@ -223,9 +223,15 @@ tests/integration/api/[resource].test.ts
|
|
|
223
223
|
```
|
|
224
224
|
|
|
225
225
|
### Coverage Target
|
|
226
|
-
|
|
227
|
-
-
|
|
228
|
-
-
|
|
226
|
+
|
|
227
|
+
<!-- Respect the test pyramid: unit-heavy domain layer carries the highest coverage;
|
|
228
|
+
integration-level adapter coverage targets critical paths, not every branch.
|
|
229
|
+
Keep these in sync with coding/TEST_PLAN_TEMPLATE.md §2. -->
|
|
230
|
+
|
|
231
|
+
- Domain layer (unit): >= 99%
|
|
232
|
+
- Application layer (unit): > 90%
|
|
233
|
+
- Adapters layer (integration): critical paths covered (~70–80% — integration tests
|
|
234
|
+
exercise wiring, not every branch)
|
|
229
235
|
|
|
230
236
|
---
|
|
231
237
|
|
|
@@ -177,7 +177,7 @@ sequenceDiagram
|
|
|
177
177
|
|
|
178
178
|
## 7. Design Readiness Checklist
|
|
179
179
|
|
|
180
|
-
**All required items must pass before proceeding to S02 Architecture / S03
|
|
180
|
+
**All required items must pass before proceeding to S02 Architecture / S03 Specification.**
|
|
181
181
|
|
|
182
182
|
### Required
|
|
183
183
|
- [ ] System architecture diagram (C4 Context minimum) — present and human-verified
|
package/bin/install.js
CHANGED
|
@@ -172,17 +172,45 @@ function shouldPreserve(relPath, fileName) {
|
|
|
172
172
|
return false;
|
|
173
173
|
}
|
|
174
174
|
|
|
175
|
-
//
|
|
176
|
-
|
|
175
|
+
// Back up an existing target file to <name>.gabbe-bak before it is overwritten.
|
|
176
|
+
// The first backup wins (never overwrite an existing .gabbe-bak), so re-running
|
|
177
|
+
// install preserves the user's ORIGINAL, not a kit copy from a prior run.
|
|
178
|
+
function backupBeforeOverwrite(dst) {
|
|
179
|
+
const backup = dst + '.gabbe-bak';
|
|
180
|
+
if (!fs.existsSync(backup)) {
|
|
181
|
+
try {
|
|
182
|
+
fs.copyFileSync(dst, backup);
|
|
183
|
+
log(` ${yellow('!')} Backed up existing ${path.basename(dst)} -> ${path.basename(backup)}`);
|
|
184
|
+
} catch (e) {
|
|
185
|
+
/* best-effort backup */
|
|
186
|
+
}
|
|
187
|
+
}
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
// Copy a directory tree without ever losing user data. Preserved files are left
|
|
191
|
+
// untouched; any other differing pre-existing file is backed up to .gabbe-bak
|
|
192
|
+
// before being refreshed. With force=true, even preserved files are re-templated
|
|
193
|
+
// (still backed up first). Mirrors init.py safe_merge_directory.
|
|
194
|
+
function safeCopyTree(srcRoot, dstRoot, force) {
|
|
177
195
|
if (!fs.existsSync(srcRoot)) return 0;
|
|
178
196
|
let copied = 0;
|
|
179
197
|
for (const src of walk(srcRoot)) {
|
|
180
198
|
const rel = path.relative(srcRoot, src);
|
|
181
199
|
const dst = path.join(dstRoot, rel);
|
|
182
200
|
const fileName = path.basename(src);
|
|
183
|
-
|
|
201
|
+
const exists = fs.existsSync(dst);
|
|
202
|
+
if (exists && !force && shouldPreserve(rel, fileName)) {
|
|
184
203
|
continue;
|
|
185
204
|
}
|
|
205
|
+
if (exists) {
|
|
206
|
+
let differs = true;
|
|
207
|
+
try {
|
|
208
|
+
differs = !fs.readFileSync(src).equals(fs.readFileSync(dst));
|
|
209
|
+
} catch (e) {
|
|
210
|
+
differs = true;
|
|
211
|
+
}
|
|
212
|
+
if (differs) backupBeforeOverwrite(dst);
|
|
213
|
+
}
|
|
186
214
|
fs.mkdirSync(path.dirname(dst), { recursive: true });
|
|
187
215
|
fs.copyFileSync(src, dst);
|
|
188
216
|
copied += 1;
|
|
@@ -411,7 +439,7 @@ Examples:
|
|
|
411
439
|
`;
|
|
412
440
|
|
|
413
441
|
function parseArgs(argv) {
|
|
414
|
-
const opts = { command: null, agents: [], yes: false, wizard: false, help: false };
|
|
442
|
+
const opts = { command: null, agents: [], yes: false, wizard: false, help: false, force: false };
|
|
415
443
|
for (let i = 0; i < argv.length; i++) {
|
|
416
444
|
const a = argv[i];
|
|
417
445
|
if (a === 'init') {
|
|
@@ -420,6 +448,8 @@ function parseArgs(argv) {
|
|
|
420
448
|
opts.help = true;
|
|
421
449
|
} else if (a === '--yes' || a === '-y') {
|
|
422
450
|
opts.yes = true;
|
|
451
|
+
} else if (a === '--force') {
|
|
452
|
+
opts.force = true;
|
|
423
453
|
} else if (a === '--wizard') {
|
|
424
454
|
opts.wizard = true;
|
|
425
455
|
} else if (a === '--agents') {
|
|
@@ -496,13 +526,13 @@ function runInit(opts) {
|
|
|
496
526
|
if (path.resolve(targetAgents) === path.resolve(SOURCE_AGENTS_DIR)) {
|
|
497
527
|
log(` ${blue('→')} Target agents/ is the source; skipping copy.`);
|
|
498
528
|
} else {
|
|
499
|
-
const n = safeCopyTree(SOURCE_AGENTS_DIR, targetAgents);
|
|
529
|
+
const n = safeCopyTree(SOURCE_AGENTS_DIR, targetAgents, opts.force);
|
|
500
530
|
log(` ${green('✓')} Copied agents/ (${n} files, user content preserved)`);
|
|
501
531
|
}
|
|
502
532
|
if (fs.existsSync(SOURCE_DOCS_DIR)) {
|
|
503
533
|
const targetDocs = path.join(PROJECT_ROOT, 'docs');
|
|
504
534
|
if (path.resolve(targetDocs) !== path.resolve(SOURCE_DOCS_DIR)) {
|
|
505
|
-
const n = safeCopyTree(SOURCE_DOCS_DIR, targetDocs);
|
|
535
|
+
const n = safeCopyTree(SOURCE_DOCS_DIR, targetDocs, opts.force);
|
|
506
536
|
log(` ${green('✓')} Copied docs/ (${n} files)`);
|
|
507
537
|
}
|
|
508
538
|
}
|
package/docs/CLI_REFERENCE.md
CHANGED
|
@@ -438,7 +438,7 @@ gabbe registry add ./bundle --namespace ext # dry run
|
|
|
438
438
|
gabbe registry add https://example/skill.skill.md --apply
|
|
439
439
|
```
|
|
440
440
|
|
|
441
|
-
### `gabbe setup`
|
|
441
|
+
### `gabbe setup [--force]`
|
|
442
442
|
|
|
443
443
|
Run the interactive install wizard (`scripts/init.py`) to wire the kit into your
|
|
444
444
|
coding agents. (For a Python-independent install, use `npx gabbe-kit init` or
|
|
@@ -446,6 +446,42 @@ coding agents. (For a Python-independent install, use `npx gabbe-kit init` or
|
|
|
446
446
|
|
|
447
447
|
```bash
|
|
448
448
|
gabbe setup
|
|
449
|
+
gabbe setup --force # re-template even preserved files (each backed up first)
|
|
450
|
+
```
|
|
451
|
+
|
|
452
|
+
**Behavior:**
|
|
453
|
+
- **Never-clobber.** Any differing pre-existing file is backed up to `<name>.gabbe-bak`
|
|
454
|
+
before being refreshed; nothing you already had is silently overwritten. The
|
|
455
|
+
preserve-set (`AGENTS.md`, `CONSTITUTION.md`, `TASKS.md`, `policies.yml`, `config.json`)
|
|
456
|
+
is left untouched unless you pass `--force`, which re-templates them too (still backing
|
|
457
|
+
each up first).
|
|
458
|
+
- **Reversible.** The wizard writes `.gabbe/manifest.json` recording everything it created
|
|
459
|
+
(copied kit files, wiring symlinks, generated skill trees, config files), so
|
|
460
|
+
`gabbe uninstall` fully reverses a wizard install.
|
|
461
|
+
- **Brownfield autodetect.** In an existing codebase (detects `package.json`,
|
|
462
|
+
`pyproject.toml`, `go.mod`, `Cargo.toml`, `composer.json`, `pom.xml`, `Gemfile`, a `.git`
|
|
463
|
+
repo, etc.) the wizard adds a Mode question — greenfield vs **Upgrade / Refactor
|
|
464
|
+
existing** — prefills detected language / framework / package-manager / project-name as
|
|
465
|
+
defaults, and in refactor mode scaffolds a `BROWNFIELD_ONBOARDING.md` discovery brief
|
|
466
|
+
instead of greenfield mission docs. The greenfield flow is unchanged in an empty dir.
|
|
467
|
+
- **Placeholder population.** Derivable `[PLACEHOLDER:]` fields in `AGENTS.md`
|
|
468
|
+
(dev/test/lint/format/typecheck/coverage commands, `repo_url`, `ci_cd`,
|
|
469
|
+
`deployment_target`) are auto-filled; the rest are kept, tagged
|
|
470
|
+
`<!-- OPTIONAL: fill this in yourself -->`, and listed in an end-of-install warning so
|
|
471
|
+
blank fields are never shipped silently.
|
|
472
|
+
|
|
473
|
+
**Node installer (`npx gabbe-kit init`) flags** — the Python-independent equivalent
|
|
474
|
+
supports the same never-clobber/`--force` behavior plus non-interactive install:
|
|
475
|
+
|
|
476
|
+
| Flag | Description |
|
|
477
|
+
|---|---|
|
|
478
|
+
| `--yes` | Non-interactive; accept defaults without prompting |
|
|
479
|
+
| `--agents <list>` | Comma-separated agents to wire (e.g. `--agents claude,cursor`) |
|
|
480
|
+
| `--force` | Re-template even preserve-set files (each backed up to `<name>.gabbe-bak` first) |
|
|
481
|
+
|
|
482
|
+
```bash
|
|
483
|
+
npx gabbe-kit init --yes --agents claude,cursor
|
|
484
|
+
npx gabbe-kit init --force
|
|
449
485
|
```
|
|
450
486
|
|
|
451
487
|
---
|
|
@@ -498,10 +534,12 @@ gabbe update
|
|
|
498
534
|
### `gabbe uninstall [--agents LIST] [--dry-run] [--purge] [--global] [--dir PATH]`
|
|
499
535
|
|
|
500
536
|
Reverse a GABBE install using its `.gabbe/manifest.json`: removes exactly what was
|
|
501
|
-
installed, restores any `.bak` backups,
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
537
|
+
installed, restores any `.gabbe-bak`/`.bak` backups, preserves any file you edited after
|
|
538
|
+
install as `<name>.gabbe-bak` (rather than deleting it), prunes now-empty wiring dirs, and
|
|
539
|
+
never touches unrelated files. Wizard installs (`gabbe setup`) are manifest-tracked and so
|
|
540
|
+
fully reversible. `--agents` deselects specific agents only; `--dry-run` prints the plan
|
|
541
|
+
without changing anything; `--purge` also removes the `agents/` kit and `.gabbe/`.
|
|
542
|
+
Idempotent and isolated (never writes outside the target).
|
|
505
543
|
|
|
506
544
|
```bash
|
|
507
545
|
gabbe uninstall --dry-run
|
package/docs/INSTALL.md
CHANGED
|
@@ -4,11 +4,13 @@ GABBE installs are **isolated**: nothing is ever written outside the chosen targ
|
|
|
4
4
|
unless you pass `--global`.
|
|
5
5
|
|
|
6
6
|
> **Reversibility — scope.** Manifest-backed, precise `update`/`uninstall` (recorded
|
|
7
|
-
> in `.gabbe/manifest.json`) covers kits managed by the Python `gabbe` CLI
|
|
8
|
-
>
|
|
9
|
-
> manifest
|
|
10
|
-
>
|
|
11
|
-
>
|
|
7
|
+
> in `.gabbe/manifest.json`) covers kits managed by the Python `gabbe` CLI **and**
|
|
8
|
+
> the Python wizard (`gabbe setup` / `python scripts/init.py`), which now writes a
|
|
9
|
+
> manifest recording everything it created under the project (copied kit files,
|
|
10
|
+
> wiring symlinks, generated skill trees, config files). So `gabbe uninstall` fully
|
|
11
|
+
> reverses a wizard install too. The remaining Python-independent installers
|
|
12
|
+
> (`npx gabbe-kit init`, `curl … | sh`) copy the kit but do **not** write a manifest,
|
|
13
|
+
> so `gabbe uninstall` cannot auto-reverse them — remove those manually (delete the
|
|
12
14
|
> created `agents/`, `.agents/`, per-agent dirs, and root `AGENTS.md`), or run
|
|
13
15
|
> `gabbe update` from a checkout to begin manifest tracking.
|
|
14
16
|
|
|
@@ -21,6 +23,14 @@ unless you pass `--global`.
|
|
|
21
23
|
| Shell bootstrap | `curl -fsSL https://raw.githubusercontent.com/andreibesleaga/GABBE/main/install.sh \| sh` | picks the best available installer |
|
|
22
24
|
| Git checkout | `git clone … && python3 scripts/init.py` | the interactive wizard |
|
|
23
25
|
|
|
26
|
+
**Never-clobber + `--force`.** Both installers — the Node installer
|
|
27
|
+
(`npx gabbe-kit init`) and the Python wizard (`gabbe setup` / `python scripts/init.py`)
|
|
28
|
+
— back up ANY differing pre-existing file to `<name>.gabbe-bak` before refreshing it, so
|
|
29
|
+
nothing you already had is silently overwritten. The preserve-set (`AGENTS.md`,
|
|
30
|
+
`CONSTITUTION.md`, `TASKS.md`, `policies.yml`, `config.json`) is left as-is unless you
|
|
31
|
+
pass `--force` (e.g. `npx gabbe-kit init --force`), which opts into re-templating those
|
|
32
|
+
too — and still backs each one up first.
|
|
33
|
+
|
|
24
34
|
After installing, run `gabbe doctor` to print an environment + install report
|
|
25
35
|
(detected OS/arch, runtimes, agent clients, and per-check PASS/WARN). It also prints
|
|
26
36
|
**post-install next steps** — which MCP servers to enable and how. For the full
|
|
@@ -62,11 +72,14 @@ pwsh ./uninstall.ps1 -DryRun # Windows / PowerShell
|
|
|
62
72
|
```
|
|
63
73
|
|
|
64
74
|
Uninstall reads `.gabbe/manifest.json`, removes **exactly** what was installed,
|
|
65
|
-
restores any shadowed user files from their `.bak
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
75
|
+
restores any shadowed user files from their `.gabbe-bak`/`.bak` backup, preserves any
|
|
76
|
+
file you edited after install as `<name>.gabbe-bak` instead of deleting it, prunes
|
|
77
|
+
now-empty wiring directories, and is idempotent (safe to run twice). When a manifest is
|
|
78
|
+
present the result is byte-identical to the pre-install state. The wizard
|
|
79
|
+
(`gabbe setup` / `python scripts/init.py`) now writes a manifest, so its installs are
|
|
80
|
+
fully reversible too. **Note:** only `npx` / `curl` installs remain non-manifest-tracked
|
|
81
|
+
(see the scope note at the top); for those, delete the kit directories manually or run
|
|
82
|
+
`gabbe update` from a checkout first.
|
|
70
83
|
|
|
71
84
|
## Verification
|
|
72
85
|
|