feat: arch voice for plugin

Author: ivklgn

.archcore/.sync-state.json

@@ -3366,6 +3366,11 @@
       "source": "plugin/context-filtering-pipeline.doc.md",
       "target": "plugin/commands-system.spec.md",
       "type": "related"
+    },
+    {
+      "source": "plugin/architect-voice-default.adr.md",
+      "target": "plugin/precision-over-coverage.adr.md",
+      "type": "extends"
     }
   ]
 }

.archcore/plugin/architect-voice-default.adr.md

@@ -0,0 +1,34 @@
+---
+title: "Architect Voice as Default Documentation Style"
+status: accepted
+tags:
+  - "architecture"
+  - "plugin"
+  - "precision"
+---
+
+## Context
+
+Research across all plugin prompts (`precision-rules.md`, `agents/archcore-assistant.md`, 7 SKILL.md files) found no content style constraint: agents composing `.archcore/` documents defaulted to developer-style output — implementation code, function signatures, and step-by-step code walkthroughs in document types where architectural rationale is the primary signal. Documents serving as AI agent context deliver higher signal-to-noise when they capture *why* decisions were made and *what they cost*, not *how* implementations work — the code is already readable from `@path/to/file` references in source.
+
+## Decision
+
+Adopted **architect voice** as the default content standard: expert, concise, precise, and argued. A document should let a senior engineer understand *why*, *what*, and *what it costs* in 30 seconds. `@path/to/file` references, identifiers, measurements, and version strings are used freely — they are the architect's vocabulary. Pasting code bodies, implementation walkthroughs, and AI-padded filler are defects. The constraint is codified in `skills/_shared/precision-rules.md` Rule 6 and `agents/archcore-assistant.md` Quality Standards. Code blocks remain appropriate for types where the exact textual format is the artifact: `rule` (Good/Bad), `guide` (steps), `cpat` (Before/After), and on explicit user request.
+
+## Alternatives Considered
+
+1. **Add voice rule to MCP server instructions (`internal/mcp/server.go`)** — rejected because MCP instructions are host-agnostic and serve Cursor, Copilot, Codex CLI, and Claude Code equally; Claude Code-specific narrative preferences do not belong in a shared layer.
+2. **Modify CLI templates (`templates/templates.go`) to remove code placeholders** — ruled out because templates define document *structure*, not voice; removing code blocks from `spec` or `doc` templates would break valid use cases where code is genuinely normative (wire formats, protocol contracts).
+3. **No change, rely on per-user prompting** — deferred; creates inconsistent defaults where each new user gets developer-style output until they discover an override.
+
+## Consequences
+
+- [expected] ADR, RFC, PRD, plan, and spec documents produced without explicit user override will contain argued rationale rather than implementation detail — shorter, faster for AI agents to process.
+- Tradeoff: users who need inline code examples in non-code-native types must explicitly request them; the escape hatch is always available but not the default.
+- [expected] Per-composition token overhead from Rule 6 and agent definition additions: ~190 tokens (~6–8% on a typical `create_document` workflow).
+- Rule 6 is a behavioral default, not a structural gate — `bin/check-precision` does not enforce it.
+
+## Superseded when
+
+- User research shows ≥ 30% of first-time users explicitly request inline code in ADRs or PRDs before being prompted — indicating the default misaligns with actual usage patterns.
+- A content-profile system is introduced that allows per-type voice configuration in `.archcore/settings.json`.

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "archcore",
   "description": "Make your AI agent code with your project's architecture, rules, and decisions.",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "author": {
     "name": "Archcore"
   },

.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "archcore",
   "description": "Make your AI agent code with your project's architecture, rules, and decisions.",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "author": {
     "name": "Archcore",
     "url": "https://archcore.ai"

.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "archcore",
   "displayName": "Archcore",
   "description": "Make your AI agent code with your project's architecture, rules, and decisions.",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "author": {
     "name": "Archcore"
   },

agents/archcore-assistant.md

@@ -92,3 +92,10 @@ When reviewing or creating documents, ensure:
 - Tags are relevant and consistent with existing tags
 - Relations capture real semantic links, not just proximity
 - Status reflects reality (draft work is `draft`, decided work is `accepted`)
+- **Architect voice**: Expert, concise, precise, argued. A senior engineer
+  reads the document in 30 seconds and knows *why*, *what*, and *what it
+  costs*. Use `@path/to/file`, identifiers, measurements, and `@`-references
+  freely. Avoid pasting code bodies — reference the source instead. Avoid
+  filler and implementation walkthroughs that add no architectural signal.
+  Code blocks belong in `rule`/`guide`/`cpat` or when explicitly requested.
+  See `skills/_shared/precision-rules.md` Rule 6.

agents/archcore-assistant.toml

@@ -72,4 +72,11 @@ When reviewing or creating documents, ensure:
 - Tags are relevant and consistent with existing tags
 - Relations capture real semantic links, not just proximity
 - Status reflects reality (draft work is `draft`, decided work is `accepted`)
+- **Architect voice**: Expert, concise, precise, argued. A senior engineer
+  reads the document in 30 seconds and knows *why*, *what*, and *what it
+  costs*. Use `@path/to/file`, identifiers, measurements, and `@`-references
+  freely. Avoid pasting code bodies — reference the source instead. Avoid
+  filler and implementation walkthroughs that add no architectural signal.
+  Code blocks belong in `rule`/`guide`/`cpat` or when explicitly requested.
+  See `skills/_shared/precision-rules.md` Rule 6.
 """

bin/check-precision

@@ -14,6 +14,8 @@
 #   4. Body length above placeholder threshold
 #   5. No cross-document body references to other .archcore/ documents
 #      (precision-rules.rule.md Rule 5 — relations belong in the graph)
+#   6. No multi-line code blocks (>=5 content lines) in architect-voice types
+#      (precision-rules.rule.md Rule 6 — use @references instead)
 
 SCRIPT_DIR=$(dirname "$0")
 # shellcheck source=lib/normalize-stdin.sh
@@ -136,6 +138,35 @@ if [ -n "$CROSS_HITS" ]; then
   add_finding "body references other .archcore/ documents ($CROSS_HITS) — move these links to the relation graph via mcp__archcore__add_relation"
 fi
 
+# --- Check 6: Multi-line code blocks in architect-voice types ---
+# Source of truth: skills/_shared/precision-rules.md Rule 6.
+# Code blocks with >=5 content lines signal pasted implementation detail;
+# types where architect voice applies must prefer @path/to/file references.
+# Exempted types (code blocks are the artifact): rule, guide, cpat.
+case "$DOC_TYPE" in
+  adr|rfc|doc|prd|idea|plan|mrd|brd|urd|brs|strs|syrs|srs)
+    LONG_BLOCK=$(printf '%s' "$BODY" | awk '
+      /^[[:space:]]*```/ {
+        if (in_block) {
+          # closing fence: check accumulated line count
+          if (block_lines >= 5) { found = 1; exit }
+          in_block = 0
+          block_lines = 0
+        } else {
+          in_block = 1
+          block_lines = 0
+        }
+        next
+      }
+      in_block { block_lines++ }
+      END { if (found) print "yes" }
+    ')
+    if [ "$LONG_BLOCK" = "yes" ]; then
+      add_finding "code block >=5 lines in $DOC_TYPE — architect voice prefers @path/to/file references over pasted implementation detail (Rule 6)"
+    fi
+    ;;
+esac
+
 # --- Emit soft warnings if any ---
 if [ -n "$FINDINGS" ]; then
   archcore_hook_info "Precision check on $ARCHCORE_DOC_PATH (soft, non-blocking) — $FINDINGS. See skills/_shared/precision-rules.md and adr-contract.md (plugin-shipped)."

skills/_shared/precision-rules.md

@@ -78,6 +78,33 @@ composing documents of type `adr`, `spec`, `rule`, `guide`. See also
   belong in the relation graph (`mcp__archcore__add_relation`), not in the
   body.
 
+6. **Architect voice: expert, concise, precise, argued.** Documents are
+   decision records and context maps — not implementation walkthroughs. The
+   target quality is: a senior engineer reads it in 30 seconds and knows
+   *why* this exists, *what* was decided, and *what it costs*. Verbose
+   AI-padded prose that restates the obvious is a defect.
+
+   **Use freely:**
+   - `@path/to/file` references, commit hashes, PR links, issue numbers
+   - Inline code for identifiers, function names, type names, version strings,
+     CLI flags — anything that names a concrete artifact
+   - Measurements, thresholds, SLOs, dates — exact values beat adjectives
+
+   **Avoid:**
+   - Pasting function bodies or multi-line code blocks where a `@reference`
+     would suffice — the source file is readable; the document is not its copy
+   - Filler phrases ("This document describes...", "In summary, we can see...")
+   - Generic implementation detail that adds no architectural signal
+
+   **Code blocks belong** in types where the exact textual format IS the
+   artifact: `rule` (Good/Bad examples), `guide` (terminal steps), `cpat`
+   (Before/After). Also appropriate in any type when the user explicitly
+   requests them or when the format itself is normative (wire protocol,
+   config schema, CLI interface).
+
+   This default applies to: `adr`, `rfc`, `doc`, `prd`, `idea`, `plan`, `mrd`,
+   `brd`, `urd`, `brs`, `strs`, `syrs`, `srs`.
+
 ## Enforcement
 
 - The plugin's `bin/check-precision` PostToolUse hook detects forbidden lexicon

skills/init/SKILL.md

@@ -55,6 +55,10 @@ Each non-empty mode additionally runs hotspot capture-candidate proposal (Step 6
 
 ## Execution
 
+Content voice: default to architectural prose — decisions, rationale, intent.
+See `skills/_shared/precision-rules.md` Rule 6. Code blocks only where the
+document type requires it (`rule`, `guide`, `cpat`) or the user asks.
+
 ### Pre-flight: CLI availability check
 
 Before any init step, verify that the Archcore CLI is available on PATH. The canonical installer is documented at https://docs.archcore.ai/cli/install/ — use it as the single source of truth; do **not** suggest other channels (`brew`, `go install`, etc.) even if the user mentions them.