pi-aia-asf 0.5.0 → 0.6.1

package/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.1] - 2026-08-28
+
+### Removed
+
+- **pi-intercom is no longer a dependency** (reversal of the 0.4.0 addition,
+  per user decision): removed from `dependencies` in package.json and from the
+  runtime dependency check — `/asf` summary is back to the four required
+  packages (pi-vigilant, pi-smart-web-search, pi-smart-fetch, pi-aia-browser).
+  ASF works fully without it; intercom is documented as an **optional** tool
+  (`pi install npm:pi-intercom`) in the README, 06d-delegation.md, and the
+  SKILL.md delegation note. Rationale: a hard dependency broke the workspace
+  installer's `--skip=pi-intercom` semantics (npm pulled it back in via
+  pi-aia-asf), and delegation is a nice-to-have, not a requirement.
+
+## [0.6.0] - 2026-08-28
+
+### Added
+
+- **06c Rule 9 — Documents are code: refactor them when they outgrow
+  editability** (new mandatory rule, Ai Applied tenet): when a document starts
+  causing writing/editing issues (edit-tool matching failures, truncation,
+  multi-topic bloat, every change touching the same big file), it is time to
+  refactor it — split by topic, keep the parent as an index/map, keep
+  cross-references exact, preserve content (Rule 8 applied to documents),
+  verify, and refactor before it hurts rather than after.
+- **Wiring**: 06c "Where this applies" (Phase 6 + Phase 7), 06c anti-patterns
+  (letting a document grow until edits break; wall-of-prose SKILL.md), SKILL.md
+  Phase 6 note, Phase 7 modularity DoD (documents too), SKILL.md anti-pattern,
+  and the reference index (now 9 rules).
+
 ## [0.5.0] - 2026-08-28
 
 ### Added

package/README.md

@@ -41,9 +41,8 @@ You can also force/start a session explicitly:
 | **pi-smart-web-search** | `web_search` | `pi install npm:pi-smart-web-search` |
 | **pi-smart-fetch** | `web_fetch`, `batch_web_fetch` | `pi install npm:pi-smart-fetch` |
 | **pi-aia-browser** | `browser_init`, `browser_navigate`, … (Playwright + Chromium, auto-installed) | `pi install npm:pi-aia-browser` |
-| **pi-intercom** | `intercom` — message other live pi sessions directly (delegation, cross-session verification) | `pi install npm:pi-intercom` |
 
-`pi-intercom` is also declared in `dependencies` in `package.json`, so `npm install` of this package pulls it in. It is intentionally **not bundled** into the tarball: bundling it would conflict with a top-level `pi install npm:pi-intercom` (tool name collision), so the tool must be installed at top level to register.
+**Optional:** `pi-intercom` (`intercom` — message other live pi sessions directly) is **not** a dependency; ASF works without it. Install it only if you want delegation between sessions: `pi install npm:pi-intercom`.
 
 The extension warns at startup (and on `/asf` with no args) when any dependency is missing.
 

package/index.ts

@@ -215,12 +215,6 @@ function checkDependencies(): DependencyCheck[] {
         existsSync(join(gitDir, "github.com", "brunoj", "pi-aia-browser")),
       hint: "pi install npm:pi-aia-browser (installs Playwright + Chromium)",
     },
-    {
-      name: "pi-intercom (intercom: message other pi sessions)",
-      package: "pi-intercom",
-      present: existsSync(join(npmDir, "pi-intercom")),
-      hint: "pi install npm:pi-intercom",
-    },
   ];
 
   return checks;
@@ -230,7 +224,7 @@ function dependencySummary(): string {
   const checks = checkDependencies();
   const missing = checks.filter((c) => !c.present);
   if (missing.length === 0) {
-    return "All ASF dependencies present: pi-vigilant, pi-smart-web-search, pi-smart-fetch, pi-aia-browser, pi-intercom ✓";
+    return "All ASF dependencies present: pi-vigilant, pi-smart-web-search, pi-smart-fetch, pi-aia-browser ✓";
   }
   return (
     "⚠️ ASF dependencies missing — install before starting a project:\n" +

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-aia-asf",
-  "version": "0.5.0",
-  "description": "Ai Applied Agentic Software Factory — codifies the full software development flow: intake, research, spec capture, adversarial analysis, planning with approval gates, test-first implementation, and release. Requires pi-vigilant, pi-smart-web-search, pi-smart-fetch, pi-aia-browser, and pi-intercom.",
+  "version": "0.6.1",
+  "description": "Ai Applied Agentic Software Factory — codifies the full software development flow: intake, research, spec capture, adversarial analysis, planning with approval gates, test-first implementation, and release. Requires pi-vigilant, pi-smart-web-search, pi-smart-fetch, and pi-aia-browser.",
   "keywords": [
     "pi-package",
     "software-factory",
@@ -48,9 +48,6 @@
     "@earendil-works/pi-coding-agent": "*",
     "typebox": "*"
   },
-  "dependencies": {
-    "pi-intercom": "^0.10.1"
-  },
   "peerDependenciesMeta": {
     "@earendil-works/pi-ai": {
       "optional": false

package/skills/aia-asf/SKILL.md

@@ -180,11 +180,15 @@ Keep the plan **implementation-ready**: any competent engineer (or agent) can ex
 > SSOT); no hardcoding (config-driven); **testable outside the host then integrated
 > verbatim** (same modules in tests and production); refactor what is too complex to
 > understand; layered with clear boundaries and an architecture writeup; full I/O debug
-> logging with replay; nothing breaks existing functionality.
+> logging with replay; nothing breaks existing functionality. **Documents are code too
+> (Rule 9): when a document outgrows editability (failing edits, truncation, multi-topic
+> bloat), split it by topic and keep the parent as an index — never let it grow until
+> editing breaks.**
 
 > **Read `references/06d-delegation.md` before delegating.** Work may be delegated two ways:
 > **intercom** (message another live pi session that owns relevant context — always `list`
-> first, say what you want back, and treat their findings as evidence, not proof), and
+> first, say what you want back, and treat their findings as evidence, not proof; **optional** —
+> only when the user has installed `pi-intercom`, ASF works without it), and
 > **subagents** (spawn an isolated `pi -p` process when the OUTCOME matters more than the
 > trace — scoped codebase research, independent parallel fixes, fresh-perspective review).
 > Two verified hard limits: **never run parallel subagents against the same file** — tested,
@@ -212,7 +216,7 @@ Execute the task list milestone by milestone. Discipline rules:
 
 Run the **Definition of Done checklist** in `references/06b-testing-qa.md` (Rule 10). Every box must hold.
 
-Also check the **modularity DoD** from `references/06c-code-quality.md` (Phase 7 section): no duplicated shared logic, no hardcoded config values, every module tested standalone with the same calls it gets in the host, architecture writeup exists, existing functionality still green.
+Also check the **modularity DoD** from `references/06c-code-quality.md` (Phase 7 section): no duplicated shared logic, no hardcoded config values, every module tested standalone with the same calls it gets in the host, architecture writeup exists, existing functionality still green. **Documents too (06c Rule 9)**: no document so large that editing it is fragile — if a doc you worked on started causing edit failures/truncation, it was refactored (split by topic, parent kept as index, cross-references updated).
 
 **Large work:** run `/asf verify` — it mechanically validates the **spec-to-code traceability matrix** (M1): every `met` spec must carry `trace` (outcome → codePath → testFile + assertion), testFile must exist, assertion must appear in it. FAIL rows block delivery. **Verify ingested specs from external planning docs too** — the doc's ✅ markers are claims, not evidence.
 
@@ -256,6 +260,7 @@ Also check the **modularity DoD** from `references/06c-code-quality.md` (Phase 7
 - ❌ Escalation/fallback logic re-implemented per caller instead of one shared escalation path
 - ❌ Shipping a module that cannot run/test standalone outside the host
 - ❌ Refactoring without the architecture writeup (see `references/06c-code-quality.md`)
+- ❌ Letting a document grow until edits start breaking instead of splitting it (06c Rule 9)
 - ❌ Running parallel subagents that touch the same file — edits are silently lost (see `references/06d-delegation.md`)
 - ❌ Trusting a subagent's exit code or self-report instead of verifying the actual code/test result
 - ❌ Re-deriving context another live session already has instead of asking it over intercom
@@ -274,6 +279,6 @@ Also check the **modularity DoD** from `references/06c-code-quality.md` (Phase 7
 - `references/05-plan.md` — PLAN.md template with examples (incl. spec-to-code traceability matrix)
 - `references/06-implementation.md` — coding discipline details (incl. M4 challenge designs, M5 trace before claiming)
 - `references/06b-testing-qa.md` — **mandatory testing & QA standard** (14 rules + definition of done)
-- `references/06c-code-quality.md` — **mandatory modularity & maintainability standard** (8 rules, SSOT, testable-standalone, single escalation path)
+- `references/06c-code-quality.md` — **mandatory modularity & maintainability standard** (9 rules, SSOT, testable-standalone, single escalation path, documents-are-code)
 - `references/06d-delegation.md` — **intercom & subagents**: when to message another session, when to spawn isolated workers, the no-mutual-dependencies rule, and why exit codes lie
 - `references/07-release.md` — release workflow (versioning, CHANGELOG, tags, npm, CI/CD)

package/skills/aia-asf/references/06c-code-quality.md

@@ -141,6 +141,38 @@ existing functionality. Each rule below carries the lesson.
 - This is the SSOT/refactor safety net: refactoring restructures *structure*,
   never *behavior*.
 
+## Rule 9 — Documents are code: refactor them when they outgrow editability
+
+> *"Whenever documents you work on become so big that they start causing
+> writing / editing issues, it's time to refactor them."* — Ai Applied tenet
+
+A document that is too big to edit safely is a **maintainability bug**, not a
+fact of life. The same triggers that say "extract a module" for code say
+"split this document" for docs:
+
+- **Edit-tool failures**: `oldText` matching starts failing or needs huge
+  context; edits become fragile and overlapping.
+- **Truncation**: the file approaches context limits; reads get cut off;
+  you can no longer see the whole document.
+- **Multi-topic bloat**: one file covers several distinct subjects (e.g. a
+  SKILL.md that has grown into a wall of prose instead of a map).
+- **Every change touches the same big file**: constant conflict risk, slow
+  review, no single place to look.
+
+**The refactor pattern (documents):**
+
+1. **Split by topic** — one subject per document (like one responsibility per
+   module). Move detail into focused references; keep the parent as an
+   **index/map** that points to them.
+2. **Keep cross-references exact** — every pointer to the old content is
+   updated; nothing dangles.
+3. **Preserve content** — a doc refactor moves text, it does not rewrite or
+   drop it (Rule 8 applied to documents).
+4. **Verify** — re-read the split docs, confirm every referenced rule/topic
+   still exists and is reachable, and that the frontmatter/format stays valid.
+5. **Refactor before it hurts, not after** — if you notice edit friction
+   starting, that is the moment. Do not wait for a broken edit.
+
 ---
 
 ## Where this applies in ASF
@@ -152,11 +184,14 @@ existing functionality. Each rule below carries the lesson.
   their boundaries, the one-way dependencies, where shared truth lives, and
   how each module is tested standalone.
 - **Phase 6 (implementation)**: apply Rules 1–8 as you build; extract modules
-  when triggers fire; write the architecture doc alongside the code.
+  when triggers fire; write the architecture doc alongside the code. Apply
+  Rule 9 to the documents you write: SKILL.md, references, PLAN.md, README —
+  split them when they outgrow editability.
 - **Phase 7 (verification)**: the DoD checklist includes: no duplicated shared
   logic (Rule 2), no hardcoded config values (Rule 3), every module tested
   standalone with the same calls (Rule 4), architecture doc written (Rule 6),
-  existing functionality still green (Rule 8).
+  existing functionality still green (Rule 8). Documents: no doc so large that
+  editing it is fragile (Rule 9).
 
 ## Anti-patterns
 
@@ -168,3 +203,6 @@ existing functionality. Each rule below carries the lesson.
 - ❌ Refactoring "for fun" without the testability/debugging payoff
 - ❌ Shipping a module that cannot run outside the host
 - ❌ Skipping the architecture writeup ("the code is self-documenting")
+- ❌ Letting a document grow until edits start breaking instead of splitting it
+  (Rule 9)
+- ❌ A SKILL.md that is a wall of prose instead of a map to focused references

package/skills/aia-asf/references/06d-delegation.md

@@ -14,6 +14,12 @@ ASF work does not have to happen in one session, in one context window, or one t
 
 ## Part 1 — Intercom: passing messages to other sessions
 
+> **Optional capability.** `pi-intercom` is **not** a dependency of ASF — ASF
+> works fully without it. The `intercom` tool is available only when the user
+> has installed it (`pi install npm:pi-intercom`). When it is present, use it
+> as described below; when it is absent, fall back to asking the user or
+> working in one session.
+
 Other pi sessions on this machine are often working on directly relevant things: the same monorepo, an adjacent service, the package you depend on. **Use intercom to talk to them directly instead of guessing, duplicating their work, or routing everything through the user.**
 
 ### When to use intercom