@northbridge-security/secureai 0.1.13

package/docs/agents/typescript.md

@@ -0,0 +1,8 @@
+---
+name: typescript-agent
+description: Writes features, bug fixes, and documentation in TypeScript. Follows our internal best practices and coding standards.
+tools: Read, Grep, Glob, Bash, LS, Edit
+model: sonnet
+---
+
+# TypeScript Agent

package/docs/guides/README.md

@@ -0,0 +1,109 @@
+# Best Practice Guides
+
+Best practices and integration guides for AI agents working with development tools and workflows. These guides ensure consistent, high-quality output across AI tools (Claude Code, Cursor, Codex CLI, GitHub Copilot).
+
+## Available Guides
+
+| Guide                                          | Purpose                                                      | Target Audience                                | When to Apply                                                                 |
+| ---------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------- | ----------------------------------------------------------------------------- |
+| [agents.sonar.md](agents.sonar.md)             | SonarQube/SonarCloud integration for automated code quality  | AI agents, code reviewers                      | Projects using SonarQube for quality gates and security scanning              |
+| [agents.markdown.md](agents.markdown.md)       | Markdown formatting standards for AI-generated documentation | AI agents, documentation reviewers             | Documentation >50 lines (READMEs, guides, API docs, troubleshooting)          |
+| [agents.gotask.md](agents.gotask.md)           | GoTask usage guide for task automation workflows             | AI agents, task developers                     | Any project using Taskfile.yml for build automation and development workflows |
+| [agents.task-master.md](agents.task-master.md) | Task Master AI integration for structured development cycles | AI agents, project managers                    | Projects using Task Master for iterative task management via MCP              |
+| [github-mcp.md](github-mcp.md)                 | GitHub MCP server integration for repository operations      | AI agents, developers configuring GitHub tools | Projects requiring GitHub integration (PRs, issues, repo management)          |
+
+## Guide Summaries
+
+### agents.sonar.md
+
+Enables automated SonarQube/SonarCloud integration for code quality and security analysis. Teaches AI agents to download analysis results programmatically, review security hotspots, fix issues automatically, and integrate with `/pr:fix` workflow without requiring manual UI access.
+
+### agents.markdown.md
+
+Teaches AI agents to create readable documentation by showing structure and concepts upfront while hiding implementation details in collapsible sections. Applies to READMEs, API docs, and technical guides over 50 lines.
+
+### agents.gotask.md
+
+Establishes GoTask as the standard for build automation and development workflows. Covers task namespacing, dependencies, variables, and integration with secret management. Used for build/test automation and code quality checks.
+
+### agents.task-master.md
+
+Provides structured task management through MCP integration. Guides AI agents on breaking down complex features, tracking implementation progress, managing task dependencies, and enabling research-backed planning for technical decisions.
+
+### github-mcp.md
+
+Defines controlled GitHub access through MCP server with limited permissions. Ensures AI agents can read repositories and create pull requests while protecting sensitive operations. Covers token management and secure configuration.
+
+## Usage by AI Agents
+
+These guides are automatically installed and configured by the AI Toolkit installer. The installer references these guides in AI tool configuration files, ensuring consistent best practices across all supported agents.
+
+### Claude Code
+
+**Auto-Configured**: Referenced in `CLAUDE.md` and loaded automatically.
+
+**How It Helps**:
+
+- Generates well-structured documentation following markdown standards
+- Uses GoTask commands for build automation instead of direct shell commands
+- Integrates Task Master MCP for structured task management
+- Accesses GitHub via MCP with limited permissions (read repos, create PRs)
+
+### Cursor IDE
+
+**Auto-Configured**: Installer adds rules to `.cursor/settings.json`.
+
+**How It Helps**:
+
+- Applies markdown standards when generating documentation
+- Suggests GoTask commands for common development tasks
+- Integrates with Task Master for project planning
+- Restricts GitHub operations to safe, limited scope
+
+### Codex CLI
+
+**Auto-Configured**: Installer adds references to Codex configuration.
+
+**How It Helps**:
+
+- Maintains consistent documentation format across CLI sessions
+- Recommends GoTask over ad-hoc shell scripts
+- Connects to Task Master MCP for task tracking
+- Uses GitHub MCP with controlled permissions
+
+### GitHub Copilot
+
+**Auto-Configured**: Referenced in `.github/copilot-instructions.md` if available.
+
+**How It Helps**:
+
+- Suggests markdown formatting that matches project standards
+- Recommends GoTask commands in inline suggestions
+- Limited integration (no native MCP support)
+- Follows GitHub best practices from guide
+
+## Creating New Guides
+
+When adding a new best practice guide:
+
+1. Create a new `agents.<topic>.md` file in this directory
+2. Include clear sections:
+   - Purpose and target audience
+   - Core principles
+   - Key guidelines
+   - Example use cases
+   - When to apply / when NOT to apply
+   - Practical examples
+3. Update this README:
+   - Add entry to Available Guides table
+   - Add Quick Reference section
+   - Add to "When to Apply These Guides" section
+4. Reference in [CLAUDE.md](../../CLAUDE.md) if applicable
+
+## Related Documentation
+
+- [Slash Commands](../commands/README.md) - Reusable command templates for AI agents
+- [Task Library](../../tasks/README.md) - GoTask automation scripts and utilities
+- [QA Standards](../QA.md) - Quality assurance guidelines and testing practices
+- [Installation Guide](../installer.md) - AI Toolkit installation and configuration
+- [1Password Integration](../1password.md) - Secret management setup

package/docs/guides/agents.clean.arch.md

@@ -0,0 +1,244 @@
+# Clean Architecture for AI Agents
+
+This guide establishes clean architecture principles for AI agents refactoring codebases. These patterns apply across all languages and frameworks, ensuring testable, maintainable, and scalable code.
+
+## Target Audience
+
+AI agents (Claude Code, Cursor, GitHub Copilot, etc.) working with any codebase that needs improved testability, separation of concerns, and better test coverage.
+
+## Core Principles
+
+### Separation of Concerns
+
+**The Dependency Rule**: Source code dependencies must point inward toward higher-level policies. Inner layers should not depend on outer layers.
+
+```text
+┌─────────────────────────────────────────────┐
+│  Frameworks & Drivers (UI, DB, Web, CLI)    │ ← Outer layer
+├─────────────────────────────────────────────┤
+│  Interface Adapters (Controllers, Gateways) │
+├─────────────────────────────────────────────┤
+│  Application Business Rules (Use Cases)     │
+├─────────────────────────────────────────────┤
+│  Enterprise Business Rules (Entities)       │ ← Inner layer
+└─────────────────────────────────────────────┘
+```
+
+**For system interaction refactoring**, we focus on the boundary between:
+
+- **Business Logic** (inner) - Pure functions, domain logic, validation
+- **Infrastructure** (outer) - System calls, I/O, external services
+
+### Interface-Based Boundaries
+
+Use interfaces (or protocols, traits, abstract classes) to define contracts between layers:
+
+**Benefits:**
+
+- Business logic depends on abstractions, not implementations
+- Multiple implementations (production, test, mock)
+- Easy to swap infrastructure without changing business logic
+- Clear contracts documented in code
+
+### Dependency Injection
+
+Pass dependencies through constructors or function parameters, not global singletons or imports:
+
+**Good:**
+
+```typescript
+class UserService {
+  constructor(private api: IUserAPI) {}
+  async getUser(id: string) {
+    return this.api.fetch(id);
+  }
+}
+```
+
+**Bad:**
+
+```typescript
+import { realAPI } from "./real-api";
+class UserService {
+  async getUser(id: string) {
+    return realAPI.fetch(id);
+  } // Hardcoded dependency
+}
+```
+
+### Testability First
+
+Design for testability from the start:
+
+**Unit Tests** - Test business logic in isolation with mocks
+
+- Fast (< 1ms per test)
+- Deterministic (no flakiness)
+- No external dependencies
+
+**Integration Tests** - Test real system interactions
+
+- Slower (seconds per test)
+- May require setup/teardown
+- Test against real systems
+
+## Common Patterns
+
+### Pattern 1: Repository Pattern
+
+Separate data access from business logic:
+
+```text
+IRepository (interface)
+    ↑
+    ├─ DatabaseRepository (production)
+    ├─ InMemoryRepository (testing)
+    └─ MockRepository (unit tests)
+```
+
+**Use when:**
+
+- Accessing databases
+- Reading/writing files
+- Caching systems
+
+### Pattern 2: Service Pattern
+
+Encapsulate external service calls:
+
+```text
+INotificationService (interface)
+    ↑
+    ├─ EmailService (production)
+    ├─ SMSService (production)
+    └─ MockNotificationService (testing)
+```
+
+**Use when:**
+
+- Calling external APIs
+- Sending notifications
+- Third-party integrations
+
+### Pattern 3: Gateway Pattern
+
+Abstract system operations:
+
+```text
+ISystemGateway (interface)
+    ↑
+    ├─ ShellGateway (production - executes commands)
+    └─ MockGateway (testing - returns canned responses)
+```
+
+**Use when:**
+
+- Executing shell commands
+- File system operations
+- Network calls
+
+### Pattern 4: Strategy Pattern
+
+Interchangeable algorithms or behaviors:
+
+```text
+IAuthStrategy (interface)
+    ↑
+    ├─ OAuth2Strategy
+    ├─ JWTStrategy
+    └─ MockAuthStrategy
+```
+
+**Use when:**
+
+- Multiple implementations of same behavior
+- Algorithm selection at runtime
+- Platform-specific implementations
+
+## Folder Organization
+
+### Module-Based Structure (Recommended)
+
+Organize by feature/module rather than by architectural layer:
+
+```text
+src/
+├── auth/
+│   ├── index.ts              # Public API exports
+│   ├── auth-interface.ts     # IAuthService interface
+│   ├── auth.system.ts        # System implementation (LDAP, OAuth)
+│   ├── session.ts            # Business logic
+│   └── tokens.ts             # Business logic
+├── users/
+│   ├── index.ts
+│   ├── user-repository-interface.ts
+│   ├── user-repository.system.ts
+│   └── user-service.ts
+└── payments/
+    ├── index.ts
+    ├── payment-gateway-interface.ts
+    ├── payment-gateway.system.ts
+    └── payment-processor.ts
+
+tests/mocks/
+├── auth/
+│   └── auth-mock.ts
+├── users/
+│   └── user-repository-mock.ts
+└── payments/
+    └── payment-gateway-mock.ts
+```
+
+**Benefits:**
+
+- Related code co-located (easy to find)
+- Clear module boundaries
+- Import from module: `import { authenticate } from '@/auth'`
+- Easy to test (all module code in one place)
+- Scales well (add modules without restructuring)
+- Easier to extract to microservices if needed
+
+### Layer-Based Structure (Academic)
+
+Traditional Clean Architecture organizes by layer:
+
+```text
+src/
+├── entities/           # Enterprise business rules
+├── use-cases/          # Application business rules
+├── adapters/           # Interface adapters
+└── frameworks/         # External frameworks
+
+# NOT RECOMMENDED for most projects
+```
+
+**Problems:**
+
+- Code for one feature scattered across directories
+- Hard to find related files
+- Doesn't scale (hundreds of files in one directory)
+- Violates co-location principle
+
+### Hybrid Approach
+
+For large codebases, combine both:
+
+```text
+src/
+├── modules/
+│   ├── auth/           # Feature module
+│   ├── users/          # Feature module
+│   └── payments/       # Feature module
+└── shared/
+    ├── interfaces/     # Shared contracts
+    └── utils/          # Shared utilities
+```
+
+## Language-Specific Guides
+
+For implementation details in specific languages, see:
+
+- [Clean Architecture in TypeScript](./agents.clean.arch.ts.md)
+- Python (Coming soon)
+- Ruby (Coming soon)
+- Go (Coming soon)