mirror of
https://github.com/affaan-m/everything-claude-code.git
synced 2026-04-05 08:43:29 +08:00
Add Kiro IDE support (.kiro/) (#548)
Co-authored-by: Sungmin Hong <hsungmin@amazon.com>
This commit is contained in:
Himanshu Sharma
301
.kiro/docs/longform-guide.md
Normal file
301
.kiro/docs/longform-guide.md
Normal file
@@ -0,0 +1,301 @@
|
||||
# Agentic Workflows: A Deep Dive
|
||||
|
||||
## Introduction
|
||||
|
||||
This guide explores the philosophy and practice of agentic workflows—a development methodology where AI agents become active collaborators in the software development process. Rather than treating AI as a code completion tool, agentic workflows position AI as a thinking partner that can plan, execute, review, and iterate on complex tasks.
|
||||
|
||||
## What Are Agentic Workflows?
|
||||
|
||||
Agentic workflows represent a fundamental shift in how we approach software development with AI assistance. Instead of asking an AI to "write this function" or "fix this bug," agentic workflows involve:
|
||||
|
||||
1. **Delegation of Intent**: You describe what you want to achieve, not how to achieve it
|
||||
2. **Autonomous Execution**: The agent plans and executes multi-step tasks independently
|
||||
3. **Iterative Refinement**: The agent reviews its own work and improves it
|
||||
4. **Context Awareness**: The agent maintains understanding across conversations and files
|
||||
5. **Tool Usage**: The agent uses development tools (linters, tests, formatters) to validate its work
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. Agents as Specialists
|
||||
|
||||
Rather than one general-purpose agent, agentic workflows use specialized agents for different tasks:
|
||||
|
||||
- **Planner**: Breaks down complex features into actionable tasks
|
||||
- **Code Reviewer**: Analyzes code for quality, security, and best practices
|
||||
- **TDD Guide**: Leads test-driven development workflows
|
||||
- **Security Reviewer**: Focuses exclusively on security concerns
|
||||
- **Architect**: Designs system architecture and component interactions
|
||||
|
||||
Each agent has a specific model, tool set, and prompt optimized for its role.
|
||||
|
||||
### 2. Skills as Reusable Workflows
|
||||
|
||||
Skills are on-demand workflows that agents can invoke for specific tasks:
|
||||
|
||||
- **TDD Workflow**: Red-green-refactor cycle with property-based testing
|
||||
- **Security Review**: Comprehensive security audit checklist
|
||||
- **Verification Loop**: Continuous validation and improvement cycle
|
||||
- **API Design**: RESTful API design patterns and best practices
|
||||
|
||||
Skills provide structured guidance for complex, multi-step processes.
|
||||
|
||||
### 3. Steering Files as Persistent Context
|
||||
|
||||
Steering files inject rules and patterns into every conversation:
|
||||
|
||||
- **Auto-inclusion**: Always-on rules (coding style, security, testing)
|
||||
- **File-match**: Conditional rules based on file type (TypeScript patterns for .ts files)
|
||||
- **Manual**: Context modes you invoke explicitly (dev-mode, review-mode)
|
||||
|
||||
This ensures consistency without repeating instructions.
|
||||
|
||||
### 4. Hooks as Automation
|
||||
|
||||
Hooks trigger actions automatically based on events:
|
||||
|
||||
- **File Events**: Run type checks when you save TypeScript files
|
||||
- **Tool Events**: Review code before git push, check for console.log statements
|
||||
- **Agent Events**: Summarize sessions, extract patterns for future use
|
||||
|
||||
Hooks create a safety net and capture knowledge automatically.
|
||||
|
||||
## Workflow Patterns
|
||||
|
||||
### Pattern 1: Feature Development with TDD
|
||||
|
||||
```
|
||||
1. Invoke planner agent: "Plan a user authentication feature"
|
||||
→ Agent creates task breakdown with acceptance criteria
|
||||
|
||||
2. Invoke tdd-guide agent with tdd-workflow skill
|
||||
→ Agent writes failing tests first
|
||||
→ Agent implements minimal code to pass tests
|
||||
→ Agent refactors for quality
|
||||
|
||||
3. Hooks trigger automatically:
|
||||
→ typecheck-on-edit runs after each file save
|
||||
→ code-review-on-write provides feedback after implementation
|
||||
→ quality-gate runs before commit
|
||||
|
||||
4. Invoke code-reviewer agent for final review
|
||||
→ Agent checks for edge cases, error handling, documentation
|
||||
```
|
||||
|
||||
### Pattern 2: Security-First Development
|
||||
|
||||
```
|
||||
1. Enable security-review skill for the session
|
||||
→ Security patterns loaded into context
|
||||
|
||||
2. Invoke security-reviewer agent: "Review authentication implementation"
|
||||
→ Agent checks for common vulnerabilities
|
||||
→ Agent validates input sanitization
|
||||
→ Agent reviews cryptographic usage
|
||||
|
||||
3. git-push-review hook triggers before push
|
||||
→ Agent performs final security check
|
||||
→ Agent blocks push if critical issues found
|
||||
|
||||
4. Update lessons-learned.md with security patterns
|
||||
→ extract-patterns hook suggests additions
|
||||
```
|
||||
|
||||
### Pattern 3: Refactoring Legacy Code
|
||||
|
||||
```
|
||||
1. Invoke architect agent: "Analyze this module's architecture"
|
||||
→ Agent identifies coupling, cohesion issues
|
||||
→ Agent suggests refactoring strategy
|
||||
|
||||
2. Invoke refactor-cleaner agent with verification-loop skill
|
||||
→ Agent refactors incrementally
|
||||
→ Agent runs tests after each change
|
||||
→ Agent validates behavior preservation
|
||||
|
||||
3. Invoke code-reviewer agent for quality check
|
||||
→ Agent ensures code quality improved
|
||||
→ Agent verifies documentation updated
|
||||
```
|
||||
|
||||
### Pattern 4: Bug Investigation and Fix
|
||||
|
||||
```
|
||||
1. Invoke planner agent: "Investigate why login fails on mobile"
|
||||
→ Agent creates investigation plan
|
||||
→ Agent identifies files to examine
|
||||
|
||||
2. Invoke build-error-resolver agent
|
||||
→ Agent reproduces the bug
|
||||
→ Agent writes failing test
|
||||
→ Agent implements fix
|
||||
→ Agent validates fix with tests
|
||||
|
||||
3. Invoke security-reviewer agent
|
||||
→ Agent ensures fix doesn't introduce vulnerabilities
|
||||
|
||||
4. doc-updater agent updates documentation
|
||||
→ Agent adds troubleshooting notes
|
||||
→ Agent updates changelog
|
||||
```
|
||||
|
||||
## Advanced Techniques
|
||||
|
||||
### Technique 1: Continuous Learning with Lessons Learned
|
||||
|
||||
The `lessons-learned.md` steering file acts as your project's evolving knowledge base:
|
||||
|
||||
```markdown
|
||||
---
|
||||
inclusion: auto
|
||||
description: Project-specific patterns and decisions
|
||||
---
|
||||
|
||||
## Project-Specific Patterns
|
||||
|
||||
### Authentication Flow
|
||||
- Always use JWT with 15-minute expiry
|
||||
- Refresh tokens stored in httpOnly cookies
|
||||
- Rate limit: 5 attempts per minute per IP
|
||||
|
||||
### Error Handling
|
||||
- Use Result<T, E> pattern for expected errors
|
||||
- Log errors with correlation IDs
|
||||
- Never expose stack traces to clients
|
||||
```
|
||||
|
||||
The `extract-patterns` hook automatically suggests additions after each session.
|
||||
|
||||
### Technique 2: Context Modes for Different Tasks
|
||||
|
||||
Use manual steering files to switch contexts:
|
||||
|
||||
```bash
|
||||
# Development mode: Focus on speed and iteration
|
||||
#dev-mode
|
||||
|
||||
# Review mode: Focus on quality and security
|
||||
#review-mode
|
||||
|
||||
# Research mode: Focus on exploration and learning
|
||||
#research-mode
|
||||
```
|
||||
|
||||
Each mode loads different rules and priorities.
|
||||
|
||||
### Technique 3: Agent Chaining
|
||||
|
||||
Chain specialized agents for complex workflows:
|
||||
|
||||
```
|
||||
planner → architect → tdd-guide → security-reviewer → doc-updater
|
||||
```
|
||||
|
||||
Each agent builds on the previous agent's work, creating a pipeline.
|
||||
|
||||
### Technique 4: Property-Based Testing Integration
|
||||
|
||||
Use the TDD workflow skill with property-based testing:
|
||||
|
||||
```
|
||||
1. Define correctness properties (not just examples)
|
||||
2. Agent generates property tests with fast-check
|
||||
3. Agent runs 100+ iterations to find edge cases
|
||||
4. Agent fixes issues discovered by properties
|
||||
5. Agent documents properties in code comments
|
||||
```
|
||||
|
||||
This catches bugs that example-based tests miss.
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Start with Planning
|
||||
|
||||
Always begin complex features with the planner agent. A good plan saves hours of rework.
|
||||
|
||||
### 2. Use the Right Agent for the Job
|
||||
|
||||
Don't use a general agent when a specialist exists. The security-reviewer agent will catch vulnerabilities that a general agent might miss.
|
||||
|
||||
### 3. Enable Relevant Hooks
|
||||
|
||||
Hooks provide automatic quality checks. Enable them early to catch issues immediately.
|
||||
|
||||
### 4. Maintain Lessons Learned
|
||||
|
||||
Update `lessons-learned.md` regularly. It becomes more valuable over time as it captures your project's unique patterns.
|
||||
|
||||
### 5. Review Agent Output
|
||||
|
||||
Agents are powerful but not infallible. Always review generated code, especially for security-critical components.
|
||||
|
||||
### 6. Iterate with Feedback
|
||||
|
||||
If an agent's output isn't quite right, provide specific feedback and let it iterate. Agents improve with clear guidance.
|
||||
|
||||
### 7. Use Skills for Complex Workflows
|
||||
|
||||
Don't try to describe a complex workflow in a single prompt. Use skills that encode best practices.
|
||||
|
||||
### 8. Combine Auto and Manual Steering
|
||||
|
||||
Use auto-inclusion for universal rules, file-match for language-specific patterns, and manual for context switching.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
### Pitfall 1: Over-Prompting
|
||||
|
||||
**Problem**: Providing too much detail in prompts, micromanaging the agent.
|
||||
|
||||
**Solution**: Trust the agent to figure out implementation details. Focus on intent and constraints.
|
||||
|
||||
### Pitfall 2: Ignoring Hooks
|
||||
|
||||
**Problem**: Disabling hooks because they "slow things down."
|
||||
|
||||
**Solution**: Hooks catch issues early when they're cheap to fix. The time saved far exceeds the overhead.
|
||||
|
||||
### Pitfall 3: Not Using Specialized Agents
|
||||
|
||||
**Problem**: Using the default agent for everything.
|
||||
|
||||
**Solution**: Swap to specialized agents for their domains. They have optimized prompts and tool sets.
|
||||
|
||||
### Pitfall 4: Forgetting to Update Lessons Learned
|
||||
|
||||
**Problem**: Repeating the same explanations to agents in every session.
|
||||
|
||||
**Solution**: Capture patterns in `lessons-learned.md` once, and agents will remember forever.
|
||||
|
||||
### Pitfall 5: Skipping Tests
|
||||
|
||||
**Problem**: Asking agents to "just write the code" without tests.
|
||||
|
||||
**Solution**: Use the TDD workflow. Tests document behavior and catch regressions.
|
||||
|
||||
## Measuring Success
|
||||
|
||||
### Metrics to Track
|
||||
|
||||
1. **Time to Feature**: How long from idea to production?
|
||||
2. **Bug Density**: Bugs per 1000 lines of code
|
||||
3. **Review Cycles**: How many iterations before merge?
|
||||
4. **Test Coverage**: Percentage of code covered by tests
|
||||
5. **Security Issues**: Vulnerabilities found in review vs. production
|
||||
|
||||
### Expected Improvements
|
||||
|
||||
With mature agentic workflows, teams typically see:
|
||||
|
||||
- 40-60% reduction in time to feature
|
||||
- 50-70% reduction in bug density
|
||||
- 30-50% reduction in review cycles
|
||||
- 80%+ test coverage (up from 40-60%)
|
||||
- 90%+ reduction in security issues reaching production
|
||||
|
||||
## Conclusion
|
||||
|
||||
Agentic workflows represent a paradigm shift in software development. By treating AI as a collaborative partner with specialized roles, persistent context, and automated quality checks, we can build software faster and with higher quality than ever before.
|
||||
|
||||
The key is to embrace the methodology fully: use specialized agents, leverage skills for complex workflows, maintain steering files for consistency, and enable hooks for automation. Start small with one agent or skill, experience the benefits, and gradually expand your agentic workflow toolkit.
|
||||
|
||||
The future of software development is collaborative, and agentic workflows are leading the way.
|
||||
496
.kiro/docs/security-guide.md
Normal file
496
.kiro/docs/security-guide.md
Normal file
@@ -0,0 +1,496 @@
|
||||
# Security Guide for Agentic Workflows
|
||||
|
||||
## Introduction
|
||||
|
||||
AI agents are powerful development tools, but they introduce unique security considerations. This guide covers security best practices for using agentic workflows safely and responsibly.
|
||||
|
||||
## Core Security Principles
|
||||
|
||||
### 1. Trust but Verify
|
||||
|
||||
**Principle**: Always review agent-generated code, especially for security-critical components.
|
||||
|
||||
**Why**: Agents can make mistakes, miss edge cases, or introduce vulnerabilities unintentionally.
|
||||
|
||||
**Practice**:
|
||||
- Review all authentication and authorization code manually
|
||||
- Verify cryptographic implementations against standards
|
||||
- Check input validation and sanitization
|
||||
- Test error handling for information leakage
|
||||
|
||||
### 2. Least Privilege
|
||||
|
||||
**Principle**: Grant agents only the tools and access they need for their specific role.
|
||||
|
||||
**Why**: Limiting agent capabilities reduces the blast radius of potential mistakes.
|
||||
|
||||
**Practice**:
|
||||
- Use `allowedTools` to restrict agent capabilities
|
||||
- Read-only agents (planner, architect) should not have write access
|
||||
- Review agents should not have shell access
|
||||
- Use `toolsSettings.allowedPaths` to restrict file access
|
||||
|
||||
### 3. Defense in Depth
|
||||
|
||||
**Principle**: Use multiple layers of security controls.
|
||||
|
||||
**Why**: No single control is perfect; layered defenses catch what others miss.
|
||||
|
||||
**Practice**:
|
||||
- Enable security-focused hooks (git-push-review, doc-file-warning)
|
||||
- Use the security-reviewer agent before merging
|
||||
- Maintain security steering files for consistent rules
|
||||
- Run automated security scans in CI/CD
|
||||
|
||||
### 4. Secure by Default
|
||||
|
||||
**Principle**: Security should be the default, not an afterthought.
|
||||
|
||||
**Why**: It's easier to maintain security from the start than to retrofit it later.
|
||||
|
||||
**Practice**:
|
||||
- Enable auto-inclusion security steering files
|
||||
- Use TDD workflow with security test cases
|
||||
- Include security requirements in planning phase
|
||||
- Document security decisions in lessons-learned
|
||||
|
||||
## Agent-Specific Security
|
||||
|
||||
### Planner Agent
|
||||
|
||||
**Risk**: May suggest insecure architectures or skip security requirements.
|
||||
|
||||
**Mitigation**:
|
||||
- Always include security requirements in planning prompts
|
||||
- Review plans with security-reviewer agent
|
||||
- Use security-review skill during planning
|
||||
- Document security constraints in requirements
|
||||
|
||||
**Example Secure Prompt**:
|
||||
```
|
||||
Plan a user authentication feature with these security requirements:
|
||||
- Password hashing with bcrypt (cost factor 12)
|
||||
- Rate limiting (5 attempts per minute)
|
||||
- JWT tokens with 15-minute expiry
|
||||
- Refresh tokens in httpOnly cookies
|
||||
- CSRF protection for state-changing operations
|
||||
```
|
||||
|
||||
### Code-Writing Agents (TDD Guide, Build Error Resolver)
|
||||
|
||||
**Risk**: May introduce vulnerabilities like SQL injection, XSS, or insecure deserialization.
|
||||
|
||||
**Mitigation**:
|
||||
- Enable security steering files (auto-loaded)
|
||||
- Use git-push-review hook to catch issues before commit
|
||||
- Run security-reviewer agent after implementation
|
||||
- Include security test cases in TDD workflow
|
||||
|
||||
**Common Vulnerabilities to Watch**:
|
||||
- SQL injection (use parameterized queries)
|
||||
- XSS (sanitize user input, escape output)
|
||||
- CSRF (use tokens for state-changing operations)
|
||||
- Path traversal (validate and sanitize file paths)
|
||||
- Command injection (avoid shell execution with user input)
|
||||
- Insecure deserialization (validate before deserializing)
|
||||
|
||||
### Security Reviewer Agent
|
||||
|
||||
**Risk**: May miss subtle vulnerabilities or provide false confidence.
|
||||
|
||||
**Mitigation**:
|
||||
- Use as one layer, not the only layer
|
||||
- Combine with automated security scanners
|
||||
- Review findings manually
|
||||
- Update security steering files with new patterns
|
||||
|
||||
**Best Practice**:
|
||||
```
|
||||
1. Run security-reviewer agent
|
||||
2. Run automated scanner (Snyk, SonarQube, etc.)
|
||||
3. Manual review of critical components
|
||||
4. Document findings in lessons-learned
|
||||
```
|
||||
|
||||
### Refactor Cleaner Agent
|
||||
|
||||
**Risk**: May accidentally remove security checks during refactoring.
|
||||
|
||||
**Mitigation**:
|
||||
- Use verification-loop skill to validate behavior preservation
|
||||
- Include security tests in test suite
|
||||
- Review diffs carefully for removed security code
|
||||
- Run security-reviewer after refactoring
|
||||
|
||||
## Hook Security
|
||||
|
||||
### Git Push Review Hook
|
||||
|
||||
**Purpose**: Catch security issues before they reach the repository.
|
||||
|
||||
**Configuration**:
|
||||
```json
|
||||
{
|
||||
"name": "git-push-review",
|
||||
"version": "1.0.0",
|
||||
"description": "Review code before git push",
|
||||
"enabled": true,
|
||||
"when": {
|
||||
"type": "preToolUse",
|
||||
"toolTypes": ["shell"]
|
||||
},
|
||||
"then": {
|
||||
"type": "askAgent",
|
||||
"prompt": "Review the code for security issues before pushing. Check for: SQL injection, XSS, CSRF, authentication bypasses, information leakage, and insecure cryptography. Block the push if critical issues are found."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Best Practice**: Keep this hook enabled always, especially for production branches.
|
||||
|
||||
### Console Log Check Hook
|
||||
|
||||
**Purpose**: Prevent accidental logging of sensitive data.
|
||||
|
||||
**Configuration**:
|
||||
```json
|
||||
{
|
||||
"name": "console-log-check",
|
||||
"version": "1.0.0",
|
||||
"description": "Check for console.log statements",
|
||||
"enabled": true,
|
||||
"when": {
|
||||
"type": "fileEdited",
|
||||
"patterns": ["*.js", "*.ts", "*.tsx"]
|
||||
},
|
||||
"then": {
|
||||
"type": "runCommand",
|
||||
"command": "grep -n 'console\\.log' \"$KIRO_FILE_PATH\" && echo 'Warning: console.log found' || true"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Why**: Console logs can leak sensitive data (passwords, tokens, PII) in production.
|
||||
|
||||
### Doc File Warning Hook
|
||||
|
||||
**Purpose**: Prevent accidental modification of critical documentation.
|
||||
|
||||
**Configuration**:
|
||||
```json
|
||||
{
|
||||
"name": "doc-file-warning",
|
||||
"version": "1.0.0",
|
||||
"description": "Warn before modifying documentation files",
|
||||
"enabled": true,
|
||||
"when": {
|
||||
"type": "preToolUse",
|
||||
"toolTypes": ["write"]
|
||||
},
|
||||
"then": {
|
||||
"type": "askAgent",
|
||||
"prompt": "If you're about to modify a README, SECURITY, or LICENSE file, confirm this is intentional and the changes are appropriate."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Steering File Security
|
||||
|
||||
### Security Steering File
|
||||
|
||||
**Purpose**: Inject security rules into every conversation.
|
||||
|
||||
**Key Rules to Include**:
|
||||
```markdown
|
||||
---
|
||||
inclusion: auto
|
||||
description: Security best practices and vulnerability prevention
|
||||
---
|
||||
|
||||
# Security Rules
|
||||
|
||||
## Input Validation
|
||||
- Validate all user input on the server side
|
||||
- Use allowlists, not denylists
|
||||
- Sanitize input before use
|
||||
- Reject invalid input, don't try to fix it
|
||||
|
||||
## Authentication
|
||||
- Use bcrypt/argon2 for password hashing (never MD5/SHA1)
|
||||
- Implement rate limiting on authentication endpoints
|
||||
- Use secure session management (httpOnly, secure, sameSite cookies)
|
||||
- Implement account lockout after failed attempts
|
||||
|
||||
## Authorization
|
||||
- Check authorization on every request
|
||||
- Use principle of least privilege
|
||||
- Implement role-based access control (RBAC)
|
||||
- Never trust client-side authorization checks
|
||||
|
||||
## Cryptography
|
||||
- Use TLS 1.3 for transport security
|
||||
- Use established libraries (don't roll your own crypto)
|
||||
- Use secure random number generators
|
||||
- Rotate keys regularly
|
||||
|
||||
## Data Protection
|
||||
- Encrypt sensitive data at rest
|
||||
- Never log passwords, tokens, or PII
|
||||
- Use parameterized queries (prevent SQL injection)
|
||||
- Sanitize output (prevent XSS)
|
||||
|
||||
## Error Handling
|
||||
- Never expose stack traces to users
|
||||
- Log errors securely with correlation IDs
|
||||
- Use generic error messages for users
|
||||
- Implement proper exception handling
|
||||
```
|
||||
|
||||
### Language-Specific Security
|
||||
|
||||
**TypeScript/JavaScript**:
|
||||
```markdown
|
||||
- Use Content Security Policy (CSP) headers
|
||||
- Sanitize HTML with DOMPurify
|
||||
- Use helmet.js for Express security headers
|
||||
- Validate with Zod/Yup, not manual checks
|
||||
- Use prepared statements for database queries
|
||||
```
|
||||
|
||||
**Python**:
|
||||
```markdown
|
||||
- Use parameterized queries with SQLAlchemy
|
||||
- Sanitize HTML with bleach
|
||||
- Use secrets module for random tokens
|
||||
- Validate with Pydantic
|
||||
- Use Flask-Talisman for security headers
|
||||
```
|
||||
|
||||
**Go**:
|
||||
```markdown
|
||||
- Use html/template for HTML escaping
|
||||
- Use crypto/rand for random generation
|
||||
- Use prepared statements with database/sql
|
||||
- Validate with validator package
|
||||
- Use secure middleware for HTTP headers
|
||||
```
|
||||
|
||||
## MCP Server Security
|
||||
|
||||
### Risk Assessment
|
||||
|
||||
MCP servers extend agent capabilities but introduce security risks:
|
||||
|
||||
- **Network Access**: Servers can make external API calls
|
||||
- **File System Access**: Some servers can read/write files
|
||||
- **Credential Storage**: Servers may require API keys
|
||||
- **Code Execution**: Some servers can execute arbitrary code
|
||||
|
||||
### Secure MCP Configuration
|
||||
|
||||
**1. Review Server Permissions**
|
||||
|
||||
Before installing an MCP server, review what it can do:
|
||||
```bash
|
||||
# Check server documentation
|
||||
# Understand what APIs it calls
|
||||
# Review what data it accesses
|
||||
```
|
||||
|
||||
**2. Use Environment Variables for Secrets**
|
||||
|
||||
Never hardcode API keys in `mcp.json`:
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-github"],
|
||||
"env": {
|
||||
"GITHUB_TOKEN": "${GITHUB_TOKEN}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**3. Limit Server Scope**
|
||||
|
||||
Use least privilege for API tokens:
|
||||
- GitHub: Use fine-grained tokens with minimal scopes
|
||||
- Cloud providers: Use service accounts with minimal permissions
|
||||
- Databases: Use read-only credentials when possible
|
||||
|
||||
**4. Review Server Code**
|
||||
|
||||
For open-source MCP servers:
|
||||
```bash
|
||||
# Clone and review the source
|
||||
git clone https://github.com/org/mcp-server
|
||||
cd mcp-server
|
||||
# Review for security issues
|
||||
grep -r "eval\|exec\|shell" .
|
||||
```
|
||||
|
||||
**5. Use Auto-Approve Carefully**
|
||||
|
||||
Only auto-approve tools you fully trust:
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"autoApprove": ["search_repositories", "get_file_contents"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Never auto-approve:
|
||||
- File write operations
|
||||
- Shell command execution
|
||||
- Database modifications
|
||||
- API calls that change state
|
||||
|
||||
## Secrets Management
|
||||
|
||||
### Never Commit Secrets
|
||||
|
||||
**Risk**: Secrets in version control can be extracted from history.
|
||||
|
||||
**Prevention**:
|
||||
```bash
|
||||
# Add to .gitignore
|
||||
echo ".env" >> .gitignore
|
||||
echo ".kiro/settings/mcp.json" >> .gitignore
|
||||
echo "secrets/" >> .gitignore
|
||||
|
||||
# Use git-secrets or similar tools
|
||||
git secrets --install
|
||||
git secrets --register-aws
|
||||
```
|
||||
|
||||
### Use Environment Variables
|
||||
|
||||
**Good**:
|
||||
```bash
|
||||
# .env file (not committed)
|
||||
DATABASE_URL=postgresql://user:pass@localhost/db
|
||||
API_KEY=sk-...
|
||||
|
||||
# Load in application
|
||||
export $(cat .env | xargs)
|
||||
```
|
||||
|
||||
**Bad**:
|
||||
```javascript
|
||||
// Hardcoded secret (never do this!)
|
||||
const apiKey = "sk-1234567890abcdef";
|
||||
```
|
||||
|
||||
### Rotate Secrets Regularly
|
||||
|
||||
- API keys: Every 90 days
|
||||
- Database passwords: Every 90 days
|
||||
- JWT signing keys: Every 30 days
|
||||
- Refresh tokens: On suspicious activity
|
||||
|
||||
### Use Secret Management Services
|
||||
|
||||
For production:
|
||||
- AWS Secrets Manager
|
||||
- HashiCorp Vault
|
||||
- Azure Key Vault
|
||||
- Google Secret Manager
|
||||
|
||||
## Incident Response
|
||||
|
||||
### If an Agent Generates Vulnerable Code
|
||||
|
||||
1. **Stop**: Don't merge or deploy the code
|
||||
2. **Analyze**: Understand the vulnerability
|
||||
3. **Fix**: Correct the issue manually or with security-reviewer agent
|
||||
4. **Test**: Verify the fix with security tests
|
||||
5. **Document**: Add pattern to lessons-learned.md
|
||||
6. **Update**: Improve security steering files to prevent recurrence
|
||||
|
||||
### If Secrets Are Exposed
|
||||
|
||||
1. **Revoke**: Immediately revoke exposed credentials
|
||||
2. **Rotate**: Generate new credentials
|
||||
3. **Audit**: Check for unauthorized access
|
||||
4. **Clean**: Remove secrets from git history (git-filter-repo)
|
||||
5. **Prevent**: Update .gitignore and pre-commit hooks
|
||||
|
||||
### If a Security Issue Reaches Production
|
||||
|
||||
1. **Assess**: Determine severity and impact
|
||||
2. **Contain**: Deploy hotfix or take system offline
|
||||
3. **Notify**: Inform affected users if required
|
||||
4. **Investigate**: Determine root cause
|
||||
5. **Remediate**: Fix the issue permanently
|
||||
6. **Learn**: Update processes to prevent recurrence
|
||||
|
||||
## Security Checklist
|
||||
|
||||
### Before Starting Development
|
||||
|
||||
- [ ] Security steering files enabled (auto-inclusion)
|
||||
- [ ] Security-focused hooks enabled (git-push-review, console-log-check)
|
||||
- [ ] MCP servers reviewed and configured securely
|
||||
- [ ] Secrets management strategy in place
|
||||
- [ ] .gitignore includes sensitive files
|
||||
|
||||
### During Development
|
||||
|
||||
- [ ] Security requirements included in planning
|
||||
- [ ] TDD workflow includes security test cases
|
||||
- [ ] Input validation on all user input
|
||||
- [ ] Output sanitization for all user-facing content
|
||||
- [ ] Authentication and authorization implemented correctly
|
||||
- [ ] Cryptography uses established libraries
|
||||
- [ ] Error handling doesn't leak information
|
||||
|
||||
### Before Merging
|
||||
|
||||
- [ ] Code reviewed by security-reviewer agent
|
||||
- [ ] Automated security scanner run (Snyk, SonarQube)
|
||||
- [ ] Manual review of security-critical code
|
||||
- [ ] No secrets in code or configuration
|
||||
- [ ] No console.log statements with sensitive data
|
||||
- [ ] Security tests passing
|
||||
|
||||
### Before Deploying
|
||||
|
||||
- [ ] Security headers configured (CSP, HSTS, etc.)
|
||||
- [ ] TLS/HTTPS enabled
|
||||
- [ ] Rate limiting configured
|
||||
- [ ] Monitoring and alerting set up
|
||||
- [ ] Incident response plan documented
|
||||
- [ ] Secrets rotated if needed
|
||||
|
||||
## Resources
|
||||
|
||||
### Tools
|
||||
|
||||
- **Static Analysis**: SonarQube, Semgrep, CodeQL
|
||||
- **Dependency Scanning**: Snyk, Dependabot, npm audit
|
||||
- **Secret Scanning**: git-secrets, truffleHog, GitGuardian
|
||||
- **Runtime Protection**: OWASP ZAP, Burp Suite
|
||||
|
||||
### Standards
|
||||
|
||||
- **OWASP Top 10**: https://owasp.org/www-project-top-ten/
|
||||
- **CWE Top 25**: https://cwe.mitre.org/top25/
|
||||
- **NIST Guidelines**: https://www.nist.gov/cybersecurity
|
||||
|
||||
### Learning
|
||||
|
||||
- **OWASP Cheat Sheets**: https://cheatsheetseries.owasp.org/
|
||||
- **PortSwigger Web Security Academy**: https://portswigger.net/web-security
|
||||
- **Secure Code Warrior**: https://www.securecodewarrior.com/
|
||||
|
||||
## Conclusion
|
||||
|
||||
Security in agentic workflows requires vigilance and layered defenses. By following these best practices—reviewing agent output, using security-focused agents and hooks, maintaining security steering files, and securing MCP servers—you can leverage the power of AI agents while maintaining strong security posture.
|
||||
|
||||
Remember: agents are tools that amplify your capabilities, but security remains your responsibility. Trust but verify, use defense in depth, and always prioritize security in your development workflow.
|
||||
360
.kiro/docs/shortform-guide.md
Normal file
360
.kiro/docs/shortform-guide.md
Normal file
@@ -0,0 +1,360 @@
|
||||
# Quick Reference Guide
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/yourusername/ecc-kiro-public-repo.git
|
||||
cd ecc-kiro-public-repo
|
||||
|
||||
# Install to current project
|
||||
./install.sh
|
||||
|
||||
# Install globally to ~/.kiro/
|
||||
./install.sh ~
|
||||
```
|
||||
|
||||
## Agents
|
||||
|
||||
### Swap to an Agent
|
||||
|
||||
```
|
||||
/agent swap <agent-name>
|
||||
```
|
||||
|
||||
### Available Agents
|
||||
|
||||
| Agent | Model | Use For |
|
||||
|-------|-------|---------|
|
||||
| `planner` | Opus | Breaking down complex features into tasks |
|
||||
| `code-reviewer` | Sonnet | Code quality and best practices review |
|
||||
| `tdd-guide` | Sonnet | Test-driven development workflows |
|
||||
| `security-reviewer` | Sonnet | Security audits and vulnerability checks |
|
||||
| `architect` | Opus | System design and architecture decisions |
|
||||
| `build-error-resolver` | Sonnet | Fixing build and compilation errors |
|
||||
| `doc-updater` | Haiku | Updating documentation and comments |
|
||||
| `refactor-cleaner` | Sonnet | Code refactoring and cleanup |
|
||||
| `go-reviewer` | Sonnet | Go-specific code review |
|
||||
| `python-reviewer` | Sonnet | Python-specific code review |
|
||||
| `database-reviewer` | Sonnet | Database schema and query review |
|
||||
| `e2e-runner` | Sonnet | End-to-end test creation and execution |
|
||||
| `harness-optimizer` | Opus | Test harness optimization |
|
||||
| `loop-operator` | Sonnet | Verification loop execution |
|
||||
| `chief-of-staff` | Opus | Project coordination and planning |
|
||||
| `go-build-resolver` | Sonnet | Go build error resolution |
|
||||
|
||||
## Skills
|
||||
|
||||
### Invoke a Skill
|
||||
|
||||
Type `/` in chat and select from the menu, or use:
|
||||
|
||||
```
|
||||
#skill-name
|
||||
```
|
||||
|
||||
### Available Skills
|
||||
|
||||
| Skill | Use For |
|
||||
|-------|---------|
|
||||
| `tdd-workflow` | Red-green-refactor TDD cycle |
|
||||
| `security-review` | Comprehensive security audit |
|
||||
| `verification-loop` | Continuous validation and improvement |
|
||||
| `coding-standards` | Code style and standards enforcement |
|
||||
| `api-design` | RESTful API design patterns |
|
||||
| `frontend-patterns` | React/Vue/Angular best practices |
|
||||
| `backend-patterns` | Server-side architecture patterns |
|
||||
| `e2e-testing` | End-to-end testing strategies |
|
||||
| `golang-patterns` | Go idioms and patterns |
|
||||
| `golang-testing` | Go testing best practices |
|
||||
| `python-patterns` | Python idioms and patterns |
|
||||
| `python-testing` | Python testing (pytest, unittest) |
|
||||
| `database-migrations` | Database schema evolution |
|
||||
| `postgres-patterns` | PostgreSQL optimization |
|
||||
| `docker-patterns` | Container best practices |
|
||||
| `deployment-patterns` | Deployment strategies |
|
||||
| `search-first` | Search-driven development |
|
||||
| `agentic-engineering` | Agentic workflow patterns |
|
||||
|
||||
## Steering Files
|
||||
|
||||
### Auto-Loaded (Always Active)
|
||||
|
||||
- `coding-style.md` - Code organization and naming
|
||||
- `development-workflow.md` - Dev process and PR workflow
|
||||
- `git-workflow.md` - Commit conventions and branching
|
||||
- `security.md` - Security best practices
|
||||
- `testing.md` - Testing standards
|
||||
- `patterns.md` - Design patterns
|
||||
- `performance.md` - Performance guidelines
|
||||
- `lessons-learned.md` - Project-specific patterns
|
||||
|
||||
### File-Match (Loaded for Specific Files)
|
||||
|
||||
- `typescript-patterns.md` - For `*.ts`, `*.tsx` files
|
||||
- `python-patterns.md` - For `*.py` files
|
||||
- `golang-patterns.md` - For `*.go` files
|
||||
- `swift-patterns.md` - For `*.swift` files
|
||||
|
||||
### Manual (Invoke with #)
|
||||
|
||||
```
|
||||
#dev-mode # Development context
|
||||
#review-mode # Code review context
|
||||
#research-mode # Research and exploration context
|
||||
```
|
||||
|
||||
## Hooks
|
||||
|
||||
### View Hooks
|
||||
|
||||
Open the Agent Hooks panel in Kiro's sidebar.
|
||||
|
||||
### Available Hooks
|
||||
|
||||
| Hook | Trigger | Action |
|
||||
|------|---------|--------|
|
||||
| `quality-gate` | Manual | Run full quality check (build, types, lint, tests) |
|
||||
| `typecheck-on-edit` | Save `*.ts`, `*.tsx` | Run TypeScript type check |
|
||||
| `console-log-check` | Save `*.js`, `*.ts`, `*.tsx` | Check for console.log statements |
|
||||
| `tdd-reminder` | Create `*.ts`, `*.tsx` | Remind to write tests first |
|
||||
| `git-push-review` | Before shell command | Review before git push |
|
||||
| `code-review-on-write` | After file write | Review written code |
|
||||
| `auto-format` | Save `*.ts`, `*.tsx`, `*.js` | Auto-format with biome/prettier |
|
||||
| `extract-patterns` | Agent stops | Suggest patterns for lessons-learned |
|
||||
| `session-summary` | Agent stops | Summarize session |
|
||||
| `doc-file-warning` | Before file write | Warn about documentation files |
|
||||
|
||||
### Enable/Disable Hooks
|
||||
|
||||
Toggle hooks in the Agent Hooks panel or edit `.kiro/hooks/*.kiro.hook` files.
|
||||
|
||||
## Scripts
|
||||
|
||||
### Run Scripts Manually
|
||||
|
||||
```bash
|
||||
# Full quality check
|
||||
.kiro/scripts/quality-gate.sh
|
||||
|
||||
# Format a file
|
||||
.kiro/scripts/format.sh path/to/file.ts
|
||||
```
|
||||
|
||||
## MCP Servers
|
||||
|
||||
### Configure MCP Servers
|
||||
|
||||
1. Copy example: `cp .kiro/settings/mcp.json.example .kiro/settings/mcp.json`
|
||||
2. Edit `.kiro/settings/mcp.json` with your API keys
|
||||
3. Restart Kiro or reconnect servers from MCP Server view
|
||||
|
||||
### Available MCP Servers (Example)
|
||||
|
||||
- `github` - GitHub API integration
|
||||
- `sequential-thinking` - Enhanced reasoning
|
||||
- `memory` - Persistent memory across sessions
|
||||
- `context7` - Extended context management
|
||||
- `vercel` - Vercel deployment
|
||||
- `railway` - Railway deployment
|
||||
- `cloudflare-docs` - Cloudflare documentation
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Feature Development
|
||||
|
||||
```
|
||||
1. /agent swap planner
|
||||
"Plan a user authentication feature"
|
||||
|
||||
2. /agent swap tdd-guide
|
||||
#tdd-workflow
|
||||
"Implement the authentication feature"
|
||||
|
||||
3. /agent swap code-reviewer
|
||||
"Review the authentication implementation"
|
||||
```
|
||||
|
||||
### Bug Fix
|
||||
|
||||
```
|
||||
1. /agent swap planner
|
||||
"Investigate why login fails on mobile"
|
||||
|
||||
2. /agent swap build-error-resolver
|
||||
"Fix the login bug"
|
||||
|
||||
3. /agent swap security-reviewer
|
||||
"Ensure the fix is secure"
|
||||
```
|
||||
|
||||
### Security Audit
|
||||
|
||||
```
|
||||
1. /agent swap security-reviewer
|
||||
#security-review
|
||||
"Audit the authentication module"
|
||||
|
||||
2. Review findings and fix issues
|
||||
|
||||
3. Update lessons-learned.md with patterns
|
||||
```
|
||||
|
||||
### Refactoring
|
||||
|
||||
```
|
||||
1. /agent swap architect
|
||||
"Analyze the user module architecture"
|
||||
|
||||
2. /agent swap refactor-cleaner
|
||||
#verification-loop
|
||||
"Refactor based on the analysis"
|
||||
|
||||
3. /agent swap code-reviewer
|
||||
"Review the refactored code"
|
||||
```
|
||||
|
||||
## Tips
|
||||
|
||||
### Get the Most from Agents
|
||||
|
||||
- **Be specific about intent**: "Add user authentication with JWT" not "write some auth code"
|
||||
- **Let agents plan**: Don't micromanage implementation details
|
||||
- **Provide context**: Reference files with `#file:path/to/file.ts`
|
||||
- **Iterate with feedback**: "The error handling needs improvement" not "rewrite everything"
|
||||
|
||||
### Maintain Quality
|
||||
|
||||
- **Enable hooks early**: Catch issues immediately
|
||||
- **Use TDD workflow**: Tests document behavior and catch regressions
|
||||
- **Update lessons-learned**: Capture patterns once, use forever
|
||||
- **Review agent output**: Agents are powerful but not infallible
|
||||
|
||||
### Speed Up Development
|
||||
|
||||
- **Use specialized agents**: They have optimized prompts and tools
|
||||
- **Chain agents**: planner → tdd-guide → code-reviewer
|
||||
- **Leverage skills**: Complex workflows encoded as reusable patterns
|
||||
- **Use context modes**: #dev-mode for speed, #review-mode for quality
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Agent Not Available
|
||||
|
||||
```
|
||||
# List available agents
|
||||
/agent list
|
||||
|
||||
# Verify installation
|
||||
ls .kiro/agents/
|
||||
```
|
||||
|
||||
### Skill Not Appearing
|
||||
|
||||
```
|
||||
# Verify installation
|
||||
ls .kiro/skills/
|
||||
|
||||
# Check SKILL.md format
|
||||
cat .kiro/skills/skill-name/SKILL.md
|
||||
```
|
||||
|
||||
### Hook Not Triggering
|
||||
|
||||
1. Check hook is enabled in Agent Hooks panel
|
||||
2. Verify file patterns match: `"patterns": ["*.ts", "*.tsx"]`
|
||||
3. Check hook JSON syntax: `cat .kiro/hooks/hook-name.kiro.hook`
|
||||
|
||||
### Steering File Not Loading
|
||||
|
||||
1. Check frontmatter: `inclusion: auto` or `fileMatch` or `manual`
|
||||
2. For fileMatch, verify pattern: `fileMatchPattern: "*.ts,*.tsx"`
|
||||
3. For manual, invoke with: `#filename`
|
||||
|
||||
### Script Not Executing
|
||||
|
||||
```bash
|
||||
# Make executable
|
||||
chmod +x .kiro/scripts/*.sh
|
||||
|
||||
# Test manually
|
||||
.kiro/scripts/quality-gate.sh
|
||||
```
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **Longform Guide**: `docs/longform-guide.md` - Deep dive on agentic workflows
|
||||
- **Security Guide**: `docs/security-guide.md` - Security best practices
|
||||
- **Migration Guide**: `docs/migration-from-ecc.md` - For Claude Code users
|
||||
- **GitHub Issues**: Report bugs and request features
|
||||
- **Kiro Documentation**: https://kiro.dev/docs
|
||||
|
||||
## Customization
|
||||
|
||||
### Add Your Own Agent
|
||||
|
||||
1. Create `.kiro/agents/my-agent.json`:
|
||||
```json
|
||||
{
|
||||
"name": "my-agent",
|
||||
"description": "My custom agent",
|
||||
"prompt": "You are a specialized agent for...",
|
||||
"model": "claude-sonnet-4-5"
|
||||
}
|
||||
```
|
||||
|
||||
2. Use with: `/agent swap my-agent`
|
||||
|
||||
### Add Your Own Skill
|
||||
|
||||
1. Create `.kiro/skills/my-skill/SKILL.md`:
|
||||
```markdown
|
||||
---
|
||||
name: my-skill
|
||||
description: My custom skill
|
||||
---
|
||||
|
||||
# My Skill
|
||||
|
||||
Instructions for the agent...
|
||||
```
|
||||
|
||||
2. Use with: `/` menu or `#my-skill`
|
||||
|
||||
### Add Your Own Steering File
|
||||
|
||||
1. Create `.kiro/steering/my-rules.md`:
|
||||
```markdown
|
||||
---
|
||||
inclusion: auto
|
||||
description: My custom rules
|
||||
---
|
||||
|
||||
# My Rules
|
||||
|
||||
Rules and patterns...
|
||||
```
|
||||
|
||||
2. Auto-loaded in every conversation
|
||||
|
||||
### Add Your Own Hook
|
||||
|
||||
1. Create `.kiro/hooks/my-hook.kiro.hook`:
|
||||
```json
|
||||
{
|
||||
"name": "my-hook",
|
||||
"version": "1.0.0",
|
||||
"description": "My custom hook",
|
||||
"enabled": true,
|
||||
"when": {
|
||||
"type": "fileEdited",
|
||||
"patterns": ["*.ts"]
|
||||
},
|
||||
"then": {
|
||||
"type": "runCommand",
|
||||
"command": "echo 'File edited'"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. Toggle in Agent Hooks panel
|
||||
Reference in New Issue
Block a user