Skip to content
This repository was archived by the owner on Feb 6, 2026. It is now read-only.

Commit fa74f88

Browse files
committed
feat(si): Implement Multi-File Context System for AI Coding Tools
The System Initiative assistant context was defined in a single monolithic SI_Agent_Context.md.tmpl file (~27KB) that was used identically across all AI coding tools (Claude Code, Codex, Cursor, OpenCode.ai). This approach: - Loaded entire context into memory at startup regardless of what was needed - Couldn't leverage each tool's native multi-file capabilities - Made maintenance difficult as provider documentation grew - Provided no way to selectively access provider-specific documentation We now implemented a modular template system that splits provider documentation into separate files and uses each tool's optimal loading strategy for efficient, on-demand context access. ### Modular Template Structure **Created provider-specific templates in data/templates/providers/:** - common.md.tmpl - Core System Initiative concepts (change sets, MCP server) - aws.md.tmpl - AWS CloudFormation schema documentation - azure.md.tmpl - Microsoft Azure ARM resource documentation - hetzner.md.tmpl - Hetzner Cloud schema documentation - digitalocean.md.tmpl - DigitalOcean resource documentation - google.md.tmpl - Google Cloud resource documentation ### Tool-Specific Implementations **Claude Code - Skills with Progressive Disclosure:** - CLAUDE.md contains common content + skill usage instructions - Generates 5 provider skills in .claude/skills/{provider}-infrastructure/SKILL.md - Skills auto-discovered and invoked based on query context - Skills use 3-level progressive disclosure: metadata → instructions → resources - Includes proper YAML frontmatter with allowed-tools matching Claude settings **Codex - On-Demand Read Tool:** - AGENTS.md contains common content + instructions to use Read tool for provider docs - Creates docs/providers/{provider}.md for each provider (5 files) - Codex dynamically reads provider docs only when answering provider-specific questions - No global configuration required, works out of the box - Supports multi-provider workflows without context window bloat **Cursor - On-Demand Read Tool:** - .cursorrules contains common content + instructions to use Read tool - Shares docs/providers/ directory with Codex (5 provider files) - Cursor reads provider docs on-demand when answering provider questions - Efficient lazy loading prevents unnecessary context consumption **OpenCode - On-Demand Read Tool:** - Auto-loads AGENTS.md (shared with Codex) - Shares docs/providers/ directory with Codex and Cursor - Reads provider docs on-demand using Read tool - Works automatically without additional configuration ### Benefits ✅ Efficient context usage - Tools load only what they need, when they need it ✅ Modular maintenance - Update one provider file, all tools benefit ✅ File sharing - Codex, Cursor, and OpenCode share AGENTS.md and docs/providers/ ✅ No duplication - Single source templates, tool-specific generation strategies ✅ Native capabilities - Each tool uses its optimal loading mechanism ✅ Scalable - Add new providers by creating one template file ✅ Multi-provider support - All tools can access multiple providers in one session
1 parent fcbfa2c commit fa74f88

13 files changed

Lines changed: 1402 additions & 1184 deletions

bin/si/data/templates/SI_Agent_Context.md.tmpl

Lines changed: 0 additions & 705 deletions
This file was deleted.
Lines changed: 261 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,261 @@
1+
# AWS Components
2+
3+
System Initiative uses the CloudFormation schema through the Cloud Control
4+
service.
5+
6+
When you create AWS Components for the user, you should always create the
7+
following subscriptions if the schema allows it:
8+
9+
- /domain/extra/Region: should subscribe to a Region components /domain/region.
10+
- /secrets/AWS Credential: should subscribe to an AWS Credential components
11+
/secrets/AWS Credential
12+
13+
If no Region or AWS Credential component is present, you should tell the user to
14+
create them first.
15+
16+
If multiple Region or AWS Credential components are present, you should ask the
17+
user which they want to use.
18+
19+
If you are working with AWS IAM components:
20+
21+
- Use the schema-attributes-documentation tool to understand every field.
22+
- If you need an ARN for a subscription, try subscribing to /resource_value/Arn.
23+
24+
## 🔍 Schema Search Case Sensitivity
25+
26+
When checking for available AWS schemas (for example,
27+
`AWS::VpcLattice::Service`), **System Initiative's schema search is
28+
case-sensitive**. If a search for a schema name returns no results, try
29+
alternate casing variations, such as:
30+
31+
- `AWS::VpcLattice::Service`
32+
- `AWS::VPCLattice::Service`
33+
- `AWS::VPCLATTICE::Service`
34+
35+
Searching across multiple case variations ensures accurate discovery of AWS
36+
CloudFormation resources. For best results, always include all plausible casing
37+
patterns when verifying schema availability.
38+
39+
## Using AWS Account Component with String Templates for IAM Policies
40+
41+
When creating IAM policies that require dynamic values like AWS Account ID, use
42+
the **AWS Account** component with **String Template** components:
43+
44+
**Pattern:**
45+
46+
1. Create an **AWS Account** component to retrieve account information
47+
2. Create **String Template** components to build dynamic ARNs or policy
48+
documents
49+
3. Subscribe IAM components to the String Template's rendered output
50+
51+
**Example: GitHub OIDC Trust Policy**
52+
53+
1. Create AWS Account component:
54+
55+
```
56+
Component: aws-account-info (AWS Account)
57+
Attributes:
58+
/secrets/AWS Credential: {$source: {component: "credential-id", path: "/secrets/AWS Credential"}}
59+
```
60+
61+
2. Create String Template for OIDC Provider ARN:
62+
63+
```
64+
Component: github-oidc-provider-arn (String Template)
65+
Attributes:
66+
/domain/Template: "arn:aws:iam::<%= AccountId %>:oidc-provider/token.actions.githubusercontent.com"
67+
/domain/Variables/AccountId: {$source: {component: "aws-account-info-id", path: "/domain/AccountData/Account"}}
68+
```
69+
70+
3. Create String Template for trust policy document:
71+
72+
```
73+
Component: github-trust-policy (String Template)
74+
Attributes:
75+
/domain/Template: "{\"Version\": \"2012-10-17\", \"Statement\": [{\"Effect\": \"Allow\", \"Principal\": {\"Federated\": \"<%= OidcProviderArn %>\"}, \"Action\": \"sts:AssumeRoleWithWebIdentity\", \"Condition\": {\"StringLike\": {\"token.actions.githubusercontent.com:sub\": \"repo:orgname/reponame:ref:refs/heads/main\"}}}]}"
76+
/domain/Variables/OidcProviderArn: {$source: {component: "github-oidc-provider-arn-id", path: "/domain/Rendered/Value"}}
77+
```
78+
79+
4. Use in IAM Role:
80+
```
81+
Component: github-actions-role (AWS::IAM::Role)
82+
Attributes:
83+
/domain/AssumeRolePolicyDocument: {$source: {component: "github-trust-policy-id", path: "/domain/Rendered/Value"}}
84+
```
85+
86+
**Available AWS Account Attributes:**
87+
88+
- `/domain/AccountData/Account` - AWS Account ID (12 digits)
89+
- `/domain/AccountData/Arn` - ARN of the caller identity
90+
- `/domain/AccountData/UserId` - Unique identifier of the caller
91+
92+
**String Template Usage:**
93+
94+
- Use `<%= VariableName %>` to insert variable values
95+
- Access rendered output via `/domain/Rendered/Value`
96+
- Can nest String Templates (subscribe one template to another's output)
97+
- Use proper JSON escaping in policy documents
98+
99+
## AWS IAM Component Creation Guide
100+
101+
When creating and configuring AWS IAM components (roles, users, policies, etc.)
102+
for specific use cases, follow these guidelines:
103+
104+
### Available AWS IAM Schemas
105+
106+
These are the ONLY IAM schemas available in System Initiative:
107+
108+
- **AWS::IAM::Role** - For service roles and cross-account access
109+
- **AWS::IAM::User** - For human users or programmatic access
110+
- **AWS::IAM::Group** - For grouping users with similar permissions
111+
- **AWS::IAM::ManagedPolicy** - For reusable permission policies
112+
- **AWS::IAM::RolePolicy** - For attaching managed policies to roles (by ARN)
113+
- **AWS::IAM::UserPolicy** - For attaching managed policies to users (by ARN)
114+
- **AWS::IAM::InstanceProfile** - For EC2 instance roles
115+
116+
**IMPORTANT**: These seven schemas are the ONLY IAM-related schemas available.
117+
Do not attempt to create or reference any other IAM schemas as they do not exist
118+
in this system.
119+
120+
**Key Distinction - AWS::IAM::RolePolicy in System Initiative:**
121+
122+
- In System Initiative, **AWS::IAM::RolePolicy** is used to **attach existing
123+
managed policies** to roles by their ARN
124+
- This is different from AWS CloudFormation where RolePolicy is for inline
125+
policies
126+
- To attach a managed policy: Create AWS::IAM::RolePolicy with
127+
`/domain/PolicyArn` subscribing to the managed policy's `/resource_value/Arn`
128+
- AWS::IAM::RolePolicy does **NOT** have `/domain/extra/Region` - only
129+
`/domain/RoleName`, `/domain/PolicyArn`, and `/secrets/AWS Credential`
130+
131+
**Analyze Requirements**
132+
133+
- Based on the use case, determine which IAM components are needed
134+
- Consider security best practices (principle of least privilege)
135+
- Plan the relationships between components
136+
137+
**Query Schema Actions and Create Core IAM Components**
138+
139+
- **FIRST**: Use schema query tools to discover available actions for your
140+
target schema
141+
- Start with the primary component (usually Role or User)
142+
- Use component-create tool with appropriate schema
143+
- Configure all required properties with proper values
144+
- Note: Action names are System Initiative-specific, not standard AWS API names
145+
146+
**Configure Policies (CRITICAL - JSON Formatting)**
147+
148+
**Policy Configuration Rules:**
149+
150+
- ALWAYS provide complete, valid JSON as a string
151+
- Use proper JSON escaping for quotes
152+
- Include Version field ("2012-10-17")
153+
- Follow AWS policy syntax exactly
154+
155+
**Good Example:**
156+
157+
```
158+
Trust policy for EC2 role:
159+
"{
160+
\"Version\": \"2012-10-17\",
161+
\"Statement\": [{
162+
\"Effect\": \"Allow\",
163+
\"Principal\": { \"Service\": \"ec2.amazonaws.com\" },
164+
\"Action\": \"sts:AssumeRole\"
165+
}]
166+
}"
167+
```
168+
169+
**Bad Example:**
170+
171+
```
172+
[object Object]
173+
"{{ trust_policy }}"
174+
undefined
175+
```
176+
177+
6. **Create Supporting Components**
178+
- Add any required ManagedPolicies with specific permissions
179+
- Create InstanceProfile if needed for EC2 roles
180+
181+
7. **Configure Relationships and Attach Policies**
182+
- Use component-update to set attribute subscriptions
183+
- Link roles to instance profiles
184+
- **To attach a managed policy to a role:**
185+
1. Create AWS::IAM::ManagedPolicy with the policy document
186+
2. Create AWS::IAM::RolePolicy component
187+
3. Set `/domain/RoleName` to subscribe to the role's `/domain/RoleName`
188+
4. Set `/domain/PolicyArn` to subscribe to the managed policy's
189+
`/resource_value/Arn`
190+
5. Set `/secrets/AWS Credential` subscription
191+
- Example:
192+
```
193+
/domain/RoleName: {$source: {component: "role-id", path: "/domain/RoleName"}}
194+
/domain/PolicyArn: {$source: {component: "policy-id", path: "/resource_value/Arn"}}
195+
/secrets/AWS Credential: {$source: {component: "credential-id", path: "/secrets/AWS Credential"}}
196+
```
197+
198+
8. **Validate Configuration and Check Qualifications**
199+
- Review all components for completeness
200+
- Ensure JSON policies are properly formatted
201+
- Verify relationships are correctly established
202+
- **CRITICAL**: Query the qualifications on each schema to check for
203+
validation errors before applying the change set
204+
- Address any qualification failures before proceeding
205+
206+
## Planning Framework
207+
208+
Before creating components, analyze:
209+
210+
- What AWS services need to be accessed?
211+
- Is this for human users or service roles?
212+
- What's the minimum set of permissions required?
213+
- Are there existing policies that can be reused?
214+
- What security constraints should be applied?
215+
216+
##### Common Policy Templates
217+
218+
**S3 Read-Only Access Policy:**
219+
220+
```json
221+
{
222+
"Version": "2012-10-17",
223+
"Statement": [
224+
{
225+
"Effect": "Allow",
226+
"Action": ["s3:GetObject", "s3:ListBucket"],
227+
"Resource": ["arn:aws:s3:::bucket-name/*", "arn:aws:s3:::bucket-name"]
228+
}
229+
]
230+
}
231+
```
232+
233+
**Lambda Execution Role Trust Policy:**
234+
235+
```json
236+
{
237+
"Version": "2012-10-17",
238+
"Statement": [
239+
{
240+
"Effect": "Allow",
241+
"Principal": { "Service": "lambda.amazonaws.com" },
242+
"Action": "sts:AssumeRole"
243+
}
244+
]
245+
}
246+
```
247+
248+
**EC2 Instance Role Trust Policy:**
249+
250+
```json
251+
{
252+
"Version": "2012-10-17",
253+
"Statement": [
254+
{
255+
"Effect": "Allow",
256+
"Principal": { "Service": "ec2.amazonaws.com" },
257+
"Action": "sts:AssumeRole"
258+
}
259+
]
260+
}
261+
```

0 commit comments

Comments
 (0)