diff --git a/.kiro/README.md b/.kiro/README.md index ae4837ad0..f13710241 100644 --- a/.kiro/README.md +++ b/.kiro/README.md @@ -158,14 +158,14 @@ Steering files provide always-on rules and context that shape how the agent work | File | Inclusion | Description | |------|-----------|-------------| -| `coding-style.md` | auto | Core coding style rules: immutability, file organization, error handling, and code quality standards. Loaded in every conversation. | -| `security.md` | auto | Security best practices including mandatory checks, secret management, and security response protocol. Loaded in every conversation. | -| `testing.md` | auto | Testing requirements: 80% coverage minimum, TDD workflow, and test types (unit, integration, E2E). Loaded in every conversation. | -| `development-workflow.md` | auto | Development process, PR workflow, and collaboration patterns. Loaded in every conversation. | -| `git-workflow.md` | auto | Git commit conventions, branching strategies, and version control best practices. Loaded in every conversation. | -| `patterns.md` | auto | Common design patterns and architectural principles. Loaded in every conversation. | -| `performance.md` | auto | Performance optimization guidelines and profiling strategies. Loaded in every conversation. | -| `lessons-learned.md` | auto | Project-specific patterns and learnings. Edit this file to capture your team's conventions. Loaded in every conversation. | +| `coding-style.md` | always | Core coding style rules: immutability, file organization, error handling, and code quality standards. Loaded in every conversation. | +| `security.md` | always | Security best practices including mandatory checks, secret management, and security response protocol. Loaded in every conversation. | +| `testing.md` | always | Testing requirements: 80% coverage minimum, TDD workflow, and test types (unit, integration, E2E). Loaded in every conversation. | +| `development-workflow.md` | always | Development process, PR workflow, and collaboration patterns. Loaded in every conversation. | +| `git-workflow.md` | always | Git commit conventions, branching strategies, and version control best practices. Loaded in every conversation. | +| `patterns.md` | always | Common design patterns and architectural principles. Loaded in every conversation. | +| `performance.md` | always | Performance optimization guidelines and profiling strategies. Loaded in every conversation. | +| `lessons-learned.md` | always | Project-specific patterns and learnings. Edit this file to capture your team's conventions. Loaded in every conversation. | | `typescript-patterns.md` | fileMatch: `*.ts,*.tsx` | TypeScript-specific patterns, type safety, and best practices. Loaded when editing TypeScript files. | | `python-patterns.md` | fileMatch: `*.py` | Python-specific patterns, type hints, and best practices. Loaded when editing Python files. | | `golang-patterns.md` | fileMatch: `*.go` | Go-specific patterns, concurrency, and best practices. Loaded when editing Go files. | @@ -181,15 +181,17 @@ Steering files provide always-on rules and context that shape how the agent work | `review-mode.md` | manual | Code review context mode. Invoke with `#review-mode` for thorough reviews. | | `research-mode.md` | manual | Research context mode. Invoke with `#research-mode` for exploration and learning. | -Steering files with `auto` inclusion are loaded automatically. No action needed — they apply as soon as you install them. +Steering files with `always` inclusion are loaded automatically. No action needed — they apply as soon as you install them. + +> **Upgrading an existing install:** the installer never overwrites steering files that already exist in your project. If you installed before these files switched to `always`, change `inclusion: auto` to `inclusion: always` in the frontmatter of `coding-style.md`, `security.md`, `testing.md`, `development-workflow.md`, `git-workflow.md`, `patterns.md`, `performance.md`, and `lessons-learned.md` in your `.kiro/steering/` directory. To create your own, add a markdown file to `.kiro/steering/` with YAML frontmatter: ```yaml --- -inclusion: auto # auto | fileMatch | manual -name: my-steering # required if inclusion is auto -description: Brief explanation of what this steering file contains +inclusion: always # always | auto | fileMatch | manual +name: my-steering # required if inclusion is auto +description: Brief explanation of what this steering file contains # required if inclusion is auto fileMatchPattern: "*.ts" # required if inclusion is fileMatch --- @@ -325,14 +327,14 @@ Shell scripts used by hooks to perform quality checks and formatting. │ ├── ... and 26 more # (testing, deployment, docker, etc.) │ └── (each skill has a SKILL.md with YAML frontmatter) ├── steering/ # 22 steering files -│ ├── coding-style.md # Auto-loaded coding style rules -│ ├── security.md # Auto-loaded security rules -│ ├── testing.md # Auto-loaded testing rules -│ ├── development-workflow.md # Auto-loaded dev workflow -│ ├── git-workflow.md # Auto-loaded git workflow -│ ├── patterns.md # Auto-loaded design patterns -│ ├── performance.md # Auto-loaded performance rules -│ ├── lessons-learned.md # Auto-loaded project patterns +│ ├── coding-style.md # Always-loaded coding style rules +│ ├── security.md # Always-loaded security rules +│ ├── testing.md # Always-loaded testing rules +│ ├── development-workflow.md # Always-loaded dev workflow +│ ├── git-workflow.md # Always-loaded git workflow +│ ├── patterns.md # Always-loaded design patterns +│ ├── performance.md # Always-loaded performance rules +│ ├── lessons-learned.md # Always-loaded project patterns │ ├── typescript-patterns.md # Loaded for .ts/.tsx files │ ├── typescript-security.md # Loaded for .ts/.tsx files │ ├── python-patterns.md # Loaded for .py files @@ -395,7 +397,7 @@ All files are yours to modify after installation. The installer never overwrites 5. **Run quality gate**: Trigger the `quality-gate` hook before committing 6. **Verify comprehensively**: Use the `verification-loop` skill before creating PRs -The auto-loaded steering files (coding-style, security, testing) ensure consistent standards throughout your session. +The always-loaded steering files (coding-style, security, testing) ensure consistent standards throughout your session. ## Usage Examples @@ -466,7 +468,7 @@ kiro-cli --agent code-reviewer > /agent swap security-reviewer > "Analyze the API endpoints for security vulnerabilities" -# 4. The security.md steering file is auto-loaded, ensuring: +# 4. The security.md steering file is always-loaded, ensuring: # - No hardcoded secrets # - Proper error handling # - Secure crypto usage @@ -486,7 +488,7 @@ kiro-cli --agent python-reviewer > "Review the type hints and error handling" > /python-patterns # Invoke Python-specific patterns skill -# Language-specific steering files are auto-loaded: +# Language-specific steering files are loaded automatically on file match: # - golang-patterns.md loads when editing .go files # - python-patterns.md loads when editing .py files # - typescript-patterns.md loads when editing .ts/.tsx files diff --git a/.kiro/docs/longform-guide.md b/.kiro/docs/longform-guide.md index 2216a2cf5..34c88432a 100644 --- a/.kiro/docs/longform-guide.md +++ b/.kiro/docs/longform-guide.md @@ -41,9 +41,10 @@ Skills provide structured guidance for complex, multi-step processes. ### 3. Steering Files as Persistent Context -Steering files inject rules and patterns into every conversation: +Steering files inject rules and patterns into conversations: -- **Auto-inclusion**: Always-on rules (coding style, security, testing) +- **Always-inclusion**: Always-on rules (coding style, security, testing) +- **Auto-inclusion**: Files are automatically included when your request matches the description. - **File-match**: Conditional rules based on file type (TypeScript patterns for .ts files) - **Manual**: Context modes you invoke explicitly (dev-mode, review-mode) @@ -146,7 +147,7 @@ The `lessons-learned.md` steering file acts as your project's evolving knowledge ```markdown --- -inclusion: auto +inclusion: always description: Project-specific patterns and decisions --- @@ -236,9 +237,9 @@ If an agent's output isn't quite right, provide specific feedback and let it ite Don't try to describe a complex workflow in a single prompt. Use skills that encode best practices. -### 8. Combine Auto and Manual Steering +### 8. Combine Steering Inclusion Modes -Use auto-inclusion for universal rules, file-match for language-specific patterns, and manual for context switching. +Use always-inclusion for universal rules, auto-inclusion for context-heavy guidance that should only load when relevant, file-match for language-specific patterns, and manual for context switching. ## Common Pitfalls diff --git a/.kiro/docs/security-guide.md b/.kiro/docs/security-guide.md index c034bdfb1..fcb94a48a 100644 --- a/.kiro/docs/security-guide.md +++ b/.kiro/docs/security-guide.md @@ -49,7 +49,7 @@ AI agents are powerful development tools, but they introduce unique security con **Why**: It's easier to maintain security from the start than to retrofit it later. **Practice**: -- Enable auto-inclusion security steering files +- Enable always-inclusion security steering files - Use TDD workflow with security test cases - Include security requirements in planning phase - Document security decisions in lessons-learned @@ -81,7 +81,7 @@ Plan a user authentication feature with these security requirements: **Risk**: May introduce vulnerabilities like SQL injection, XSS, or insecure deserialization. **Mitigation**: -- Enable security steering files (auto-loaded) +- Enable security steering files (always-loaded) - Use git-push-review hook to catch issues before commit - Run security-reviewer agent after implementation - Include security test cases in TDD workflow @@ -203,7 +203,7 @@ Plan a user authentication feature with these security requirements: **Key Rules to Include**: ```markdown --- -inclusion: auto +inclusion: always description: Security best practices and vulnerability prevention --- @@ -434,7 +434,7 @@ For production: ### Before Starting Development -- [ ] Security steering files enabled (auto-inclusion) +- [ ] Security steering files enabled (always-inclusion) - [ ] Security-focused hooks enabled (git-push-review, console-log-check) - [ ] MCP servers reviewed and configured securely - [ ] Secrets management strategy in place diff --git a/.kiro/docs/shortform-guide.md b/.kiro/docs/shortform-guide.md index ace257f31..1f099eaf2 100644 --- a/.kiro/docs/shortform-guide.md +++ b/.kiro/docs/shortform-guide.md @@ -78,7 +78,7 @@ Type `/` in chat and select from the menu, or use: ## Steering Files -### Auto-Loaded (Always Active) +### Always-Loaded (Always Active) - `coding-style.md` - Code organization and naming - `development-workflow.md` - Dev process and PR workflow @@ -267,9 +267,10 @@ cat .kiro/skills/skill-name/SKILL.md ### Steering File Not Loading -1. Check frontmatter: `inclusion: auto` or `fileMatch` or `manual` +1. Check frontmatter: `inclusion: always` or `auto` or `fileMatch` or `manual` 2. For fileMatch, verify pattern: `fileMatchPattern: "*.ts,*.tsx"` -3. For manual, invoke with: `#filename` +3. For auto, verify `name` and `description` are set and the description matches your request +4. For manual, invoke with: `#filename` ### Script Not Executing @@ -326,7 +327,7 @@ Instructions for the agent... 1. Create `.kiro/steering/my-rules.md`: ```markdown --- -inclusion: auto +inclusion: always description: My custom rules --- @@ -335,7 +336,7 @@ description: My custom rules Rules and patterns... ``` -2. Auto-loaded in every conversation +2. Always-loaded in every conversation ### Add Your Own Hook diff --git a/.kiro/install.sh b/.kiro/install.sh index a987a29a4..2b2a25506 100755 --- a/.kiro/install.sh +++ b/.kiro/install.sh @@ -138,6 +138,6 @@ echo "Next steps:" echo " 1. Open your project in Kiro" echo " 2. Agents: Automatic in IDE, /agent swap in CLI" echo " 3. Skills: Available via / menu in chat" -echo " 4. Steering files with 'auto' inclusion load automatically" +echo " 4. Steering files with 'always' inclusion load automatically" echo " 5. Toggle hooks in the Agent Hooks panel" echo " 6. Copy desired MCP servers from .kiro/settings/mcp.json.example to .kiro/settings/mcp.json" diff --git a/.kiro/steering/coding-style.md b/.kiro/steering/coding-style.md index e972e9a47..12e3f07e2 100644 --- a/.kiro/steering/coding-style.md +++ b/.kiro/steering/coding-style.md @@ -1,5 +1,5 @@ --- -inclusion: auto +inclusion: always name: coding-style description: Core coding style rules including immutability, file organization, error handling, and code quality standards. --- diff --git a/.kiro/steering/development-workflow.md b/.kiro/steering/development-workflow.md index ba29d83db..89958c290 100644 --- a/.kiro/steering/development-workflow.md +++ b/.kiro/steering/development-workflow.md @@ -1,5 +1,5 @@ --- -inclusion: auto +inclusion: always name: development-workflow description: Development workflow guidelines for planning, TDD, code review, and commit pipeline --- diff --git a/.kiro/steering/git-workflow.md b/.kiro/steering/git-workflow.md index b78b2163d..3c72d2a85 100644 --- a/.kiro/steering/git-workflow.md +++ b/.kiro/steering/git-workflow.md @@ -1,5 +1,5 @@ --- -inclusion: auto +inclusion: always name: git-workflow description: Git workflow guidelines for conventional commits and pull request process --- diff --git a/.kiro/steering/lessons-learned.md b/.kiro/steering/lessons-learned.md index 0c96707dd..2287b0799 100644 --- a/.kiro/steering/lessons-learned.md +++ b/.kiro/steering/lessons-learned.md @@ -1,5 +1,5 @@ --- -inclusion: auto +inclusion: always name: lessons-learned description: Project-specific patterns, preferences, and lessons learned over time (user-editable) --- diff --git a/.kiro/steering/patterns.md b/.kiro/steering/patterns.md index 9139aa03d..570c33d0c 100644 --- a/.kiro/steering/patterns.md +++ b/.kiro/steering/patterns.md @@ -1,5 +1,5 @@ --- -inclusion: auto +inclusion: always name: patterns description: Common design patterns including repository pattern, API response format, and skeleton project approach --- diff --git a/.kiro/steering/performance.md b/.kiro/steering/performance.md index 7cae57041..2d18d5e2a 100644 --- a/.kiro/steering/performance.md +++ b/.kiro/steering/performance.md @@ -1,5 +1,5 @@ --- -inclusion: auto +inclusion: always name: performance description: Performance optimization guidelines including model selection strategy, context window management, and build troubleshooting --- diff --git a/.kiro/steering/security.md b/.kiro/steering/security.md index 335d2836d..3d68c069c 100644 --- a/.kiro/steering/security.md +++ b/.kiro/steering/security.md @@ -1,5 +1,5 @@ --- -inclusion: auto +inclusion: always name: security description: Security best practices including mandatory checks, secret management, and security response protocol. --- diff --git a/.kiro/steering/testing.md b/.kiro/steering/testing.md index e3478e7c8..a3c1522d0 100644 --- a/.kiro/steering/testing.md +++ b/.kiro/steering/testing.md @@ -1,5 +1,5 @@ --- -inclusion: auto +inclusion: always name: testing description: Testing requirements including 80% coverage, TDD workflow, and test types. --- diff --git a/tests/docs/kiro-steering-inclusion.test.js b/tests/docs/kiro-steering-inclusion.test.js new file mode 100644 index 000000000..beb3c6b91 --- /dev/null +++ b/tests/docs/kiro-steering-inclusion.test.js @@ -0,0 +1,106 @@ +/** + * Regression coverage for Kiro steering file inclusion modes. + * + * Kiro only loads a steering file in every conversation with `inclusion: always`; + * `auto` loads it only when the request matches its description. + */ + +const assert = require('assert'); +const fs = require('fs'); +const path = require('path'); + +const KIRO_DIR = path.join(__dirname, '..', '..', '.kiro'); +const STEERING_DIR = path.join(KIRO_DIR, 'steering'); +const README = path.join(KIRO_DIR, 'README.md'); + +const ALWAYS_ON = [ + 'coding-style.md', + 'security.md', + 'testing.md', + 'development-workflow.md', + 'git-workflow.md', + 'patterns.md', + 'performance.md', + 'lessons-learned.md', +]; + +function test(name, fn) { + try { + fn(); + console.log(` ✓ ${name}`); + return true; + } catch (error) { + console.log(` ✗ ${name}`); + console.log(` Error: ${error.message}`); + return false; + } +} + +function readFrontmatter(file) { + const content = fs.readFileSync(path.join(STEERING_DIR, file), 'utf8'); + const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/); + assert.ok(match, `${file} should start with YAML frontmatter`); + const fields = {}; + for (const line of match[1].split(/\r?\n/)) { + const field = line.match(/^(\w+):\s*(.*)$/); + if (field) fields[field[1]] = field[2].trim(); + } + return fields; +} + +function readReadmeInclusions() { + const readme = fs.readFileSync(README, 'utf8'); + const inclusions = {}; + for (const row of readme.matchAll(/^\| `([\w-]+\.md)` \| (always|auto|manual|fileMatch)\b/gm)) { + inclusions[row[1]] = row[2]; + } + return inclusions; +} + +function runTests() { + console.log('\n=== Testing Kiro steering inclusion modes ===\n'); + + let passed = 0; + let failed = 0; + + const steeringFiles = fs.readdirSync(STEERING_DIR).filter(file => file.endsWith('.md')); + + if (test('core steering files use always inclusion', () => { + for (const file of ALWAYS_ON) { + assert.strictEqual( + readFrontmatter(file).inclusion, + 'always', + `${file} should use inclusion: always so it loads in every conversation` + ); + } + })) passed++; else failed++; + + if (test('README steering table matches each file frontmatter', () => { + const documented = readReadmeInclusions(); + for (const file of steeringFiles) { + assert.ok(documented[file], `${file} should be listed in the .kiro/README.md steering table`); + assert.strictEqual( + readFrontmatter(file).inclusion, + documented[file], + `${file} frontmatter inclusion should match the README table` + ); + } + })) passed++; else failed++; + + if (test('steering files declare the fields their inclusion mode requires', () => { + for (const file of steeringFiles) { + const fields = readFrontmatter(file); + if (fields.inclusion === 'auto') { + assert.ok(fields.name && fields.description, `${file} uses auto inclusion and needs name and description`); + } + if (fields.inclusion === 'fileMatch') { + assert.ok(fields.fileMatchPattern, `${file} uses fileMatch inclusion and needs fileMatchPattern`); + } + } + })) passed++; else failed++; + + console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`); + process.exit(failed > 0 ? 1 : 0); +} + +runTests();