Skip to content

Commit a384488

Browse files
ddunnockddunnock
committed
docs: Update specification for RFC-0015 Primer System Redesign
Updates ACP specification to v1.3.0 with RFC-0015 compliance: Specification Updates: - ACP-1.0.md: Added tiered primer system (13.5) and context commands (13.6) - Chapter 03: Added conventions, imported_by, enhanced stats sections - Chapter 06: Added primer integration section with constraint surfacing - Chapter 10: Added query vs context distinction - Chapter 11: Added tiered system, IDE detection, foundation prompt - Chapter 14: Added acp context command with all operations New Documentation: - spec/docs/cli-primer-reference.md: Complete CLI primer/context reference - rfcs/rfc-0015-primer-redesign.md: Full RFC specification Schema Updates: - cache.schema.json: Added conventions, imported_by, stats enhancements - primer.schema.json: Updated for tiered system Examples Updated: - minimal.md, complete.md, edge-cases.md: RFC-0015 structures and commands
1 parent ccb5d6a commit a384488

15 files changed

+4531
-147
lines changed

‎primers/primers.md‎

Lines changed: 604 additions & 89 deletions
Large diffs are not rendered by default.

‎rfcs/rfc-0013-mcp-server-tool-completeness.md‎

Lines changed: 1341 additions & 0 deletions
Large diffs are not rendered by default.

‎rfcs/rfc-0015-primer-redesign.md‎

Lines changed: 1190 additions & 0 deletions
Large diffs are not rendered by default.

‎schemas/v1/cache.schema.json‎

Lines changed: 103 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
"type": "string",
1111
"description": "ACP specification version",
1212
"pattern": "^\\d+\\.\\d+\\.\\d+",
13-
"examples": ["1.0.0"]
13+
"examples": ["1.1.0"]
1414
},
1515
"generated_at": {
1616
"type": "string",
@@ -60,6 +60,40 @@
6060
"type": "integer",
6161
"minimum": 0,
6262
"description": "Total lines of code"
63+
},
64+
"languages": {
65+
"type": "array",
66+
"description": "Language distribution statistics (RFC-0015)",
67+
"items": {
68+
"type": "object",
69+
"required": ["name", "files", "percentage"],
70+
"properties": {
71+
"name": {
72+
"type": "string",
73+
"description": "Programming language identifier"
74+
},
75+
"files": {
76+
"type": "integer",
77+
"minimum": 0,
78+
"description": "Number of files in this language"
79+
},
80+
"percentage": {
81+
"type": "number",
82+
"minimum": 0,
83+
"maximum": 100,
84+
"description": "Percentage of total files"
85+
}
86+
}
87+
}
88+
},
89+
"primary_language": {
90+
"type": "string",
91+
"description": "Primary language of the project (highest percentage) (RFC-0015)"
92+
},
93+
"indexed_at": {
94+
"type": "string",
95+
"format": "date-time",
96+
"description": "When the cache was last indexed (RFC-0015)"
6397
}
6498
}
6599
},
@@ -317,6 +351,66 @@
317351
}
318352
}
319353
},
354+
"conventions": {
355+
"type": "object",
356+
"description": "Auto-detected naming and import conventions (RFC-0015)",
357+
"properties": {
358+
"file_naming": {
359+
"type": "array",
360+
"description": "File naming patterns detected per directory",
361+
"items": {
362+
"type": "object",
363+
"required": ["directory", "pattern", "confidence"],
364+
"properties": {
365+
"directory": {
366+
"type": "string",
367+
"description": "Relative directory path"
368+
},
369+
"pattern": {
370+
"type": "string",
371+
"description": "Glob-style naming pattern (e.g., '*.ts', '*.route.ts')"
372+
},
373+
"confidence": {
374+
"type": "number",
375+
"minimum": 0,
376+
"maximum": 1,
377+
"description": "Detection confidence (0.0-1.0, threshold 0.7)"
378+
},
379+
"examples": {
380+
"type": "array",
381+
"items": { "type": "string" },
382+
"description": "Example filenames matching this pattern"
383+
},
384+
"anti_patterns": {
385+
"type": "array",
386+
"items": { "type": "string" },
387+
"description": "Similar patterns NOT used (to avoid confusion)"
388+
}
389+
}
390+
}
391+
},
392+
"imports": {
393+
"type": "object",
394+
"description": "Import/module style conventions",
395+
"properties": {
396+
"module_system": {
397+
"type": "string",
398+
"enum": ["esm", "commonjs", "mixed"],
399+
"description": "JavaScript/TypeScript module system"
400+
},
401+
"path_style": {
402+
"type": "string",
403+
"enum": ["relative", "absolute", "alias", "mixed"],
404+
"description": "Import path style preference"
405+
},
406+
"index_exports": {
407+
"type": "boolean",
408+
"description": "Whether index files re-export from subdirectories"
409+
}
410+
}
411+
}
412+
}
413+
},
320414
"bridge": {
321415
"type": "object",
322416
"description": "Project-wide bridging statistics (RFC-0006)",
@@ -684,6 +778,14 @@
684778
"default": [],
685779
"description": "Imported modules"
686780
},
781+
"importedBy": {
782+
"type": "array",
783+
"items": {
784+
"type": "string"
785+
},
786+
"default": [],
787+
"description": "RFC-0015: Files that import this file (reverse import graph)"
788+
},
687789
"ai_hints": {
688790
"type": "array",
689791
"items": {

‎schemas/v1/primer.schema.json‎

Lines changed: 122 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313
"type": "string",
1414
"pattern": "^\\d+\\.\\d+\\.\\d+",
1515
"description": "Primer schema version (semver)",
16-
"examples": ["1.0.0"]
16+
"examples": ["1.1.0"]
1717
},
1818
"metadata": {
1919
"$ref": "#/$defs/metadata"
@@ -43,6 +43,9 @@
4343
},
4444
"knowledgeStore": {
4545
"$ref": "#/$defs/knowledgeStore"
46+
},
47+
"tiers": {
48+
"$ref": "#/$defs/tierConfiguration"
4649
}
4750
},
4851
"required": ["version", "sections"],
@@ -770,6 +773,124 @@
770773
},
771774
"required": ["id", "content"],
772775
"additionalProperties": false
776+
},
777+
778+
"tierConfiguration": {
779+
"type": "object",
780+
"description": "Primer tier system configuration (RFC-0015)",
781+
"properties": {
782+
"thresholds": {
783+
"type": "object",
784+
"description": "Token budget thresholds for tier selection",
785+
"properties": {
786+
"micro": {
787+
"type": "integer",
788+
"default": 300,
789+
"description": "Maximum tokens for Micro tier"
790+
},
791+
"minimal": {
792+
"type": "integer",
793+
"default": 450,
794+
"description": "Maximum tokens for Minimal tier"
795+
},
796+
"standard": {
797+
"type": "integer",
798+
"default": 700,
799+
"description": "Maximum tokens for Standard tier"
800+
},
801+
"full": {
802+
"type": "integer",
803+
"default": 1500,
804+
"description": "Token target for Full tier"
805+
}
806+
},
807+
"additionalProperties": false
808+
},
809+
"definitions": {
810+
"type": "object",
811+
"description": "Tier-specific template definitions",
812+
"additionalProperties": {
813+
"$ref": "#/$defs/tierDefinition"
814+
}
815+
},
816+
"default": {
817+
"type": "string",
818+
"enum": ["micro", "minimal", "standard", "full"],
819+
"default": "standard",
820+
"description": "Default tier when budget not specified"
821+
},
822+
"mcpReduction": {
823+
"type": "number",
824+
"minimum": 0,
825+
"maximum": 1,
826+
"default": 0.2,
827+
"description": "Token reduction factor for MCP context (0.2 = 20% smaller)"
828+
}
829+
},
830+
"additionalProperties": false
831+
},
832+
833+
"tierDefinition": {
834+
"type": "object",
835+
"description": "Definition for a single primer tier",
836+
"properties": {
837+
"name": {
838+
"type": "string",
839+
"description": "Human-readable tier name"
840+
},
841+
"maxTokens": {
842+
"type": "integer",
843+
"minimum": 1,
844+
"description": "Maximum tokens for this tier"
845+
},
846+
"template": {
847+
"type": "string",
848+
"description": "Template file path or inline template for CLI output"
849+
},
850+
"mcpTemplate": {
851+
"type": "string",
852+
"description": "Template for MCP context (reduced tokens)"
853+
},
854+
"sections": {
855+
"type": "array",
856+
"items": { "type": "string" },
857+
"description": "Section IDs to include in this tier"
858+
},
859+
"features": {
860+
"type": "object",
861+
"description": "Feature flags for this tier",
862+
"properties": {
863+
"protectedFiles": {
864+
"type": "boolean",
865+
"default": false,
866+
"description": "Include protected files list"
867+
},
868+
"hotpaths": {
869+
"type": "boolean",
870+
"default": false,
871+
"description": "Include hotpaths for sensitive code"
872+
},
873+
"namingConventions": {
874+
"type": "boolean",
875+
"default": false,
876+
"description": "Include naming conventions table"
877+
},
878+
"domains": {
879+
"type": "boolean",
880+
"default": false,
881+
"description": "Include domain structure"
882+
},
883+
"architecture": {
884+
"type": "boolean",
885+
"default": false,
886+
"description": "Include architecture overview"
887+
}
888+
},
889+
"additionalProperties": false
890+
}
891+
},
892+
"required": ["name", "maxTokens"],
893+
"additionalProperties": false
773894
}
774895
}
775896
}

‎spec/ACP-1.0.md‎

Lines changed: 56 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
# AI Context Protocol (ACP) Specification
22

3-
**Version**: 1.2.0
4-
**Date**: 2025-12-21
5-
**Status**: RFC-001 Compliant
3+
**Version**: 1.3.0
4+
**Date**: 2026-01-01
5+
**Status**: RFC-001, RFC-0015 Compliant
66

77
---
88

@@ -52,7 +52,7 @@
5252
10. [Conformance Levels](#10-conformance-levels)
5353
11. [Error Handling](#11-error-handling)
5454
12. [Versioning](#12-versioning)
55-
13. [Bootstrap & AI Integration](#13-bootstrap--ai-integration) *(RFC-001)*
55+
13. [Bootstrap & AI Integration](#13-bootstrap--ai-integration) *(RFC-001, RFC-0015)*
5656

5757
**Appendices:**
5858
- [Appendix A: Complete Annotation Reference](#appendix-a-complete-annotation-reference)
@@ -2031,6 +2031,44 @@ When AI encounters an `@acp:*` annotation:
20312031
| `acp query domain <name>` | Get domain files and relationships |
20322032
| `acp map <path>` | Get visual file map with constraints |
20332033
| `acp knowledge "q"` | Ask about the codebase |
2034+
| `acp primer` | Generate tiered AI bootstrap context (RFC-0015) |
2035+
| `acp context <operation>` | Get operation-specific context (RFC-0015) |
2036+
2037+
### 13.5 Tiered Primer System (RFC-0015)
2038+
2039+
The primer system provides AI agents with project context at different token budgets:
2040+
2041+
| Tier | Budget | CLI Tokens | Use Case |
2042+
|----------|------------|------------|------------------------------|
2043+
| Micro | <300 | ~250 | Essential safety constraints |
2044+
| Minimal | 300-449 | ~400 | Core project context |
2045+
| Standard | 450-699 | ~600 | Balanced context |
2046+
| Full | ≥700 | ~1400 | Complete understanding |
2047+
2048+
**Usage:**
2049+
```bash
2050+
acp primer --budget 500 # Standard tier
2051+
acp primer --budget 800 # Full tier
2052+
```
2053+
2054+
### 13.6 Operation-Specific Context (RFC-0015)
2055+
2056+
The `acp context` command provides context tailored to specific AI operations:
2057+
2058+
| Operation | Purpose | Key Options |
2059+
|-----------|--------------------------------------|---------------------|
2060+
| `create` | Context for creating new files | `--directory` |
2061+
| `modify` | Context for modifying existing files | `--file` (required) |
2062+
| `debug` | Context for debugging issues | `--file` (required) |
2063+
| `explore` | Context for exploring the project | *(none)* |
2064+
2065+
**Usage:**
2066+
```bash
2067+
acp context create # Get naming conventions
2068+
acp context modify --file src/auth.ts # Get constraints and dependencies
2069+
```
2070+
2071+
See [Chapter 14: Bootstrap & AI Integration](chapters/14-bootstrap.md) for complete details.
20342072

20352073
---
20362074

@@ -2848,6 +2886,20 @@ See documentation for current list and contribution guidelines.
28482886

28492887
## Changelog
28502888

2889+
### 1.3.0 (2026-01-01) - RFC-0015 Primer System Redesign
2890+
2891+
#### Added
2892+
- **Section 13.5**: Tiered Primer System with 4-tier budget-based selection (micro, minimal, standard, full)
2893+
- **Section 13.6**: Operation-Specific Context (`acp context` command with create, modify, debug, explore operations)
2894+
- **CLI Commands**: Added `acp primer` and `acp context <operation>` to Section 13.4
2895+
- **Cache enhancements**: `conventions` section for naming patterns, `imported_by` tracking, enhanced `stats`
2896+
- **IDE detection**: Automatic detection of IDE environments (Cursor, VS Code, Cline, JetBrains, Zed)
2897+
- **Foundation prompt**: `--standalone` flag for raw API usage
2898+
2899+
#### Changed
2900+
- Updated specification status to include RFC-0015 compliance
2901+
- Section 13 (Bootstrap & AI Integration) updated with tiered primer references
2902+
28512903
### 1.2.0 (2025-12-21) - Complete File Format Documentation
28522904

28532905
#### Added

0 commit comments

Comments
 (0)