this repo has no description
_scripts: add OpenSpec support for AI-assisted development
Add infrastructure for contributors to optionally use OpenSpec for
AI-assisted development with structured proposal/design/spec workflows.
Directory structure separates tracked content from local tooling:
- doc/specs/ - Main specs (source of truth, tracked)
- doc/context/ - Shared context files like language change checklist (tracked)
- openspec/ - Workflow state and config (local only, gitignored)
Setup script (_scripts/setup-openspec.sh):
- Creates openspec/config.yaml pointing to doc/specs
- Runs 'openspec init' to generate AI agent skills
- Supports 'update' mode for regenerating after OpenSpec upgrades
Updated .gitignore to exclude local-only tooling:
- openspec/, .cursor/
- AI agent skills in .claude/, .codex/, .gemini/, .github/
Updated CONTRIBUTING.md with setup instructions for contributors.
Signed-off-by: Marcel van Lohuizen <mpvl@gmail.com>
Change-Id: I1a2cae18d34922ecde8828a546bc30fb89ac5bf8
Reviewed-on: https://cue.gerrithub.io/c/cue-lang/cue/+/1231007
TryBot-Result: CUEcueckoo <cueckoo@cuelang.org>
Reviewed-by: Daniel Martí <mvdan@mvdan.cc>
Unity-Result: CUE porcuepine <cue.porcuepine@gmail.com>
+264
+14
.gitignore
+14
.gitignore
···
17
17
# Note that CI requires a clean git repo when it finishes,
18
18
# so we don't want it to think the credentials file is untracked.
19
19
gha-creds-*.json
20
+
21
+
# OpenSpec Tooling (Local only)
22
+
openspec/
23
+
24
+
# Cursor IDE
25
+
.cursor/
26
+
27
+
# AI Agent Skills/Commands (generated by OpenSpec)
28
+
.claude/skills/openspec-*/
29
+
.claude/commands/opsx/
30
+
.codex/
31
+
.gemini/
32
+
.github/prompts/opsx-*.prompt.md
33
+
.github/skills/openspec-*/
+36
CONTRIBUTING.md
+36
CONTRIBUTING.md
···
595
595
This section collects a number of other comments that are outside the
596
596
issue/edit/code review/submit process itself.
597
597
598
+
### AI-assisted development with OpenSpec
599
+
600
+
Contributors can optionally use [OpenSpec](https://github.com/Fission-AI/OpenSpec/)
601
+
for AI-assisted development. OpenSpec provides a structured workflow for creating
602
+
proposals, designs, specs, and implementation tasks with AI coding assistants like
603
+
Claude Code, GitHub Copilot, Gemini, and others.
604
+
605
+
**Setup:**
606
+
607
+
1. Install OpenSpec CLI (requires Node.js 20.19.0+):
608
+
```console
609
+
$ npm install -g @fission-ai/openspec@latest
610
+
```
611
+
612
+
2. Run the setup script from the repository root:
613
+
```console
614
+
$ ./_scripts/setup-openspec.sh
615
+
```
616
+
617
+
This creates local-only tooling files (gitignored) while specs and context are
618
+
tracked in `doc/`:
619
+
620
+
- `doc/specs/` - Main specs (source of truth, tracked)
621
+
- `doc/context/` - Shared context like language change checklists (tracked)
622
+
- `openspec/` - Workflow state and config (local only, gitignored)
623
+
624
+
**Quick start commands** (in your AI assistant):
625
+
- `/opsx:new` - Start a new change with proposal → design → specs → tasks workflow
626
+
- `/opsx:continue` - Continue working on an existing change
627
+
- `/opsx:apply` - Implement tasks from a change
628
+
629
+
**Updating after OpenSpec upgrades:**
630
+
```console
631
+
$ ./_scripts/setup-openspec.sh update
632
+
```
633
+
598
634
### Copyright headers
599
635
600
636
Files in the CUE repository don't list author names, both to avoid clutter and
+111
_scripts/setup-openspec.sh
+111
_scripts/setup-openspec.sh
···
1
+
#!/bin/bash
2
+
# Setup OpenSpec tooling for local development
3
+
#
4
+
# This script initializes the OpenSpec workflow with configurations
5
+
# pointing to the tracked doc/ directory for specs and context.
6
+
#
7
+
# PREREQUISITES
8
+
# =============
9
+
# Node.js 20.19.0 or higher is required.
10
+
#
11
+
# INSTALLATION
12
+
# ============
13
+
# Install OpenSpec CLI via npm:
14
+
#
15
+
# npm install -g @fission-ai/openspec@latest
16
+
#
17
+
# For more info: https://github.com/Fission-AI/OpenSpec/
18
+
#
19
+
# USAGE
20
+
# =====
21
+
# ./_scripts/setup-openspec.sh # First-time setup
22
+
# ./_scripts/setup-openspec.sh update # Regenerate skills after OpenSpec upgrade
23
+
#
24
+
# WHAT IT CREATES (all gitignored)
25
+
# ================================
26
+
# - openspec/config.yaml - OpenSpec configuration
27
+
# - .claude/commands/opsx/* - Claude Code commands
28
+
# - .claude/skills/openspec-*/* - Claude Code skills
29
+
# - Similar for .codex/, .gemini/, .github/ integrations
30
+
31
+
set -e
32
+
33
+
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
34
+
REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
35
+
36
+
cd "$REPO_ROOT"
37
+
38
+
MODE="$1"
39
+
40
+
echo "Setting up OpenSpec tooling..."
41
+
42
+
# Create openspec directory structure
43
+
mkdir -p openspec
44
+
45
+
# Create or update config.yaml pointing to doc/
46
+
if [[ ! -f openspec/config.yaml ]] || [[ $MODE != "update" ]]; then
47
+
cat > openspec/config.yaml <<-'EOF'
48
+
schema: spec-driven
49
+
50
+
# Path to main specs (the source of truth)
51
+
specsPath: doc/specs
52
+
53
+
# Project context (optional)
54
+
# This is shown to AI when creating artifacts.
55
+
# Add your tech stack, conventions, style guides, domain knowledge, etc.
56
+
context: |
57
+
Please refer to doc/context/language-features.md for language rules and the
58
+
comprehensive checklist for implementing language changes.
59
+
60
+
# Per-artifact rules (optional)
61
+
# Add custom rules for specific artifacts.
62
+
# Example:
63
+
# rules:
64
+
# proposal:
65
+
# - Keep proposals under 500 words
66
+
# - Always include a "Non-goals" section
67
+
# tasks:
68
+
# - Break tasks into chunks of max 2 hours
69
+
EOF
70
+
echo "Created openspec/config.yaml"
71
+
else
72
+
echo "Keeping existing openspec/config.yaml"
73
+
fi
74
+
75
+
# Check if openspec CLI is available
76
+
if command -v openspec &> /dev/null; then
77
+
if [[ $MODE == "update" ]]; then
78
+
echo "Running 'openspec update' to regenerate AI agent skills..."
79
+
openspec update
80
+
else
81
+
echo "Running 'openspec init' to generate AI agent skills..."
82
+
# Use --tools to run non-interactively; config.yaml already exists
83
+
openspec init --tools claude,codex,gemini,github-copilot
84
+
fi
85
+
else
86
+
echo ""
87
+
echo "ERROR: 'openspec' CLI not found."
88
+
echo ""
89
+
echo "Install OpenSpec first (requires Node.js 20.19.0+):"
90
+
echo " npm install -g @fission-ai/openspec@latest"
91
+
echo ""
92
+
echo "For more info: https://github.com/Fission-AI/OpenSpec/"
93
+
echo ""
94
+
echo "Then re-run this script."
95
+
exit 1
96
+
fi
97
+
98
+
echo ""
99
+
echo "Setup complete!"
100
+
echo ""
101
+
echo "Directory structure:"
102
+
echo " doc/specs/ - Main specs (tracked, source of truth)"
103
+
echo " doc/context/ - Shared context files (tracked)"
104
+
echo " openspec/ - Workflow state and config (local only, gitignored)"
105
+
echo ""
106
+
echo "Quick start:"
107
+
echo " /opsx:new - Start a new change"
108
+
echo " /opsx:continue - Continue working on a change"
109
+
echo " /opsx:apply - Implement tasks from a change"
110
+
echo ""
111
+
echo "Run './_scripts/setup-openspec.sh update' after upgrading OpenSpec."
+103
doc/context/language-features.md
+103
doc/context/language-features.md
···
1
+
# Language Features Context
2
+
3
+
This is the CUE language repository.
4
+
5
+
## Language Version Gating
6
+
7
+
- New language features MUST be gated on a minimum language version
8
+
- Features should specify the minimum version (e.g., v0.16.0) in the design
9
+
- Implementation should check c.experiments.LanguageVersion() and use semver.Compare
10
+
- Error message format: "feature X requires language version vX.Y.Z or later; current version is vA.B.C"
11
+
- The version check should be in internal/core/compile/compile.go
12
+
- See verifyVersion() for the pattern used for builtins
13
+
14
+
## Experiments
15
+
16
+
- New language features are often introduced as experiments before becoming stable
17
+
- Experiments are defined in internal/cueexperiment/file.go as fields on the File struct
18
+
- Each experiment has a tag: `experiment:"preview:vX.Y.Z"` (when introduced) and optionally `stable:vX.Y.Z` (when graduated)
19
+
- Users enable experiments via @experiment(name) attribute in CUE files
20
+
- Check experiments via c.experiments.FieldName in the compiler
21
+
- Consider using experiments for features that may need refinement based on user feedback
22
+
23
+
## Language Change Checklist
24
+
25
+
When adding new syntax or AST nodes to the CUE language, the following
26
+
packages and files typically need updates. Use this as a comprehensive
27
+
checklist when planning tasks:
28
+
29
+
### 1. Lexer & Token (cue/token/)
30
+
- [ ] token.go: Add new token constants
31
+
- [ ] token.go: Add keywords to keyword map if applicable
32
+
33
+
### 2. AST (cue/ast/)
34
+
- [ ] ast.go: Add new AST node struct(s)
35
+
- [ ] ast.go: Implement marker methods (e.g., clauseNode(), exprNode())
36
+
- [ ] ast.go: Add fields to existing structs if extending them
37
+
- [ ] walk.go: Add case for new node type in Walk function
38
+
39
+
### 3. Parser (cue/parser/)
40
+
- [ ] parser.go: Add parsing logic for new syntax
41
+
- [ ] parser_test.go: Add parser tests
42
+
43
+
### 4. AST Utilities (cue/ast/astutil/)
44
+
- [ ] apply.go: Add case for new node type in Apply function
45
+
- [ ] resolve.go: Handle new node in scope resolution if it affects scoping
46
+
47
+
### 5. AST Debug (internal/astinternal/)
48
+
- [ ] debug.go: Add case in DebugStr for new node type
49
+
50
+
### 6. Compiler - ADT Structures (internal/core/adt/)
51
+
- [ ] expr.go: Add ADT struct for new construct
52
+
- [ ] expr.go: Add fields to existing ADT structs if extending them
53
+
54
+
### 7. Compiler - Compilation (internal/core/compile/)
55
+
- [ ] compile.go: Add compilation logic for AST to ADT conversion
56
+
- [ ] compile.go: Add language version check if feature-gated
57
+
58
+
### 8. Evaluator (internal/core/adt/)
59
+
- [ ] Add evaluation logic in appropriate files (e.g., comprehension.go)
60
+
61
+
### 9. Debug Output (internal/core/debug/)
62
+
- [ ] debug.go: Add case for new ADT node type
63
+
- [ ] compact.go: Add case for new ADT node type
64
+
65
+
### 10. Walker (internal/core/walk/)
66
+
- [ ] walk.go: Add case for new ADT node type
67
+
68
+
### 11. Exporter (internal/core/export/)
69
+
- [ ] adt.go: Add export logic for new ADT node to AST conversion
70
+
71
+
### 12. Dependency Analysis (internal/core/dep/)
72
+
- [ ] dep.go: Handle new construct in dependency marking
73
+
- [ ] mixed.go: Handle new construct if applicable
74
+
75
+
### 13. Formatter (cue/format/)
76
+
- [ ] node.go: Add formatting logic for new AST node
77
+
78
+
### 14. Subsumer (internal/core/subsume/)
79
+
- [ ] structural.go: Handle new construct if it affects subsumption
80
+
81
+
### 15. Tests
82
+
- [ ] cue/testdata/: Add evaluation tests (.txtar files)
83
+
- [ ] cue/parser/parser_test.go: Add parser tests
84
+
- [ ] internal/core/dep/testdata/: Add dependency tracking tests
85
+
- [ ] internal/core/export/testdata/main/: Add export tests
86
+
87
+
### 16. Documentation
88
+
- [ ] doc/ref/spec.md: Update grammar
89
+
- [ ] doc/ref/spec.md: Add examples
90
+
- [ ] doc/ref/spec.md: Document semantics and scoping rules
91
+
92
+
### 17. Experiments (if feature is experimental)
93
+
- [ ] internal/cueexperiment/file.go: Add experiment field with tags
94
+
- [ ] internal/core/compile/compile.go: Check experiment flag before enabling
95
+
- [ ] doc/: Document experiment and how to enable it
96
+
- [ ] Consider preview/stable version tags for gradual rollout
97
+
98
+
### 18. Other Potential Updates
99
+
- [ ] cue/load/tags.go: If feature interacts with build tags
100
+
- [ ] internal/encoding/: If feature affects encoding/decoding
101
+
- [ ] internal/lsp/: If feature needs LSP support
102
+
- [ ] tools/fix/fix.go: If feature needs migration tooling
103
+
- [ ] tools/trim/: If feature affects trimming