nitm-ai-dev-toolkit 3.0.15

package/src/monorepo/.agents/skills/project-documentation/SKILL.md

@@ -0,0 +1,425 @@
+---
+name: project-documentation
+description: Standards for creating and maintaining project documentation including README files, inline comments, API documentation, and architectural decision records
+version: 1.0.0
+author: {{PROJECT_NAME}} Team
+created: 2026-01-26
+updated: 2026-01-26
+tags:
+  - documentation
+  - readme
+  - api-docs
+  - adr
+  - comments
+applies_to:
+  - "**/*.md"
+  - "**/README*"
+  - "**/CHANGELOG*"
+  - "**/docs/**"
+---
+
+# Project Documentation Standards
+
+Comprehensive guidelines for creating clear, consistent, and maintainable documentation across the monorepo.
+
+## Documentation Hierarchy
+
+### Monorepo Documentation Structure
+
+```
+{{PROJECT_NAME}}/
+├── README.md                    # Monorepo overview, quick start
+├── AGENTS.md                    # AI context for entire workspace
+├── CHANGELOG.md                 # Version history
+├── CONTRIBUTING.md              # Contribution guidelines
+├── apps/
+│   ├── {{APP_NAME_1}}/
+│   │   ├── README.md            # App-specific setup
+│   │   └── AGENTS.md            # App-specific AI context
+│   └── {{APP_NAME_2}}/
+│       ├── README.md
+│       └── AGENTS.md
+├── packages/
+│   └── {{PACKAGE_NAME}}/
+│       └── README.md            # Package documentation
+└── docs/
+    ├── architecture/            # System design
+    │   ├── overview.md
+    │   └── decisions/           # ADRs
+    ├── api/                     # API documentation
+    ├── guides/                  # How-to guides
+    └── specs/                   # Feature specifications
+```
+
+### Documentation Ownership
+
+| Document          | Owner              | Update Frequency   |
+| ----------------- | ------------------ | ------------------ |
+| Root README.md    | Platform team      | Major releases     |
+| App README.md     | App team           | Per feature        |
+| Package README.md | Package maintainer | Per change         |
+| AGENTS.md         | AI/Dev tooling     | As patterns evolve |
+| ADRs              | Relevant team      | Per decision       |
+
+## Root README.md Standards
+
+### Required Sections
+
+```markdown
+# {{PROJECT_NAME}}
+
+Brief description of what this monorepo contains and its purpose.
+
+## Quick Start
+
+\`\`\`bash
+
+# Clone and install
+
+git clone {{REPO_URL}}
+cd {{PROJECT_NAME}}
+{{PACKAGE_MANAGER}} install
+
+# Run all apps in development
+
+{{PACKAGE_MANAGER}} dev
+
+# Run specific app
+
+{{PACKAGE_MANAGER}} dev --filter={{APP_NAME_1}}
+\`\`\`
+
+## Workspace Structure
+
+| Directory                     | Purpose                   |
+| ----------------------------- | ------------------------- |
+| `apps/{{APP_NAME_1}}`         | {{APP_1_DESCRIPTION}}     |
+| `apps/{{APP_NAME_2}}`         | {{APP_2_DESCRIPTION}}     |
+| `packages/{{PACKAGE_NAME_1}}` | {{PACKAGE_1_DESCRIPTION}} |
+
+## Documentation
+
+- [Architecture Overview](./docs/architecture/overview.md)
+- [API Documentation](./docs/api/)
+- [Contributing Guide](./CONTRIBUTING.md)
+
+## Development
+
+See individual app READMEs for specific setup:
+
+- [{{APP_NAME_1}} README](./apps/{{APP_NAME_1}}/README.md)
+- [{{APP_NAME_2}} README](./apps/{{APP_NAME_2}}/README.md)
+```
+
+## App/Package README Standards
+
+### App README Template
+
+```markdown
+# {{APP_NAME}}
+
+{{APP_DESCRIPTION}}
+
+## Prerequisites
+
+- Node.js {{NODE_VERSION}}
+- {{OTHER_DEPENDENCY}}
+
+## Setup
+
+\`\`\`bash
+
+# From monorepo root
+
+{{PACKAGE_MANAGER}} install
+
+# Setup environment
+
+cp apps/{{APP_NAME}}/.env.example apps/{{APP_NAME}}/.env.local
+
+# Edit .env.local with your values
+
+\`\`\`
+
+## Development
+
+\`\`\`bash
+
+# Start development server
+
+{{PACKAGE_MANAGER}} dev --filter={{APP_NAME}}
+
+# Run tests
+
+{{PACKAGE_MANAGER}} test --filter={{APP_NAME}}
+\`\`\`
+
+## Architecture
+
+Brief overview of app architecture and key patterns.
+See [AGENTS.md](./AGENTS.md) for detailed context.
+
+## Environment Variables
+
+| Variable       | Description                | Required |
+| -------------- | -------------------------- | -------- |
+| `DATABASE_URL` | Database connection string | Yes      |
+| `API_KEY`      | External API key           | No       |
+```
+
+### Package README Template
+
+```markdown
+# @{{PROJECT_NAME}}/{{PACKAGE_NAME}}
+
+{{PACKAGE_DESCRIPTION}}
+
+## Installation
+
+\`\`\`bash
+
+# Add to your app
+
+{{PACKAGE_MANAGER}} add @{{PROJECT_NAME}}/{{PACKAGE_NAME}} --filter={{YOUR_APP}}
+\`\`\`
+
+## Usage
+
+\`\`\`typescript
+import { Component } from '@{{PROJECT_NAME}}/{{PACKAGE_NAME}}';
+
+// Basic usage
+<Component prop="value" />
+\`\`\`
+
+## API Reference
+
+### Component
+
+| Prop    | Type      | Default | Description |
+| ------- | --------- | ------- | ----------- |
+| `prop1` | `string`  | -       | Description |
+| `prop2` | `boolean` | `false` | Description |
+
+## Development
+
+\`\`\`bash
+
+# Build the package
+
+{{PACKAGE_MANAGER}} build --filter={{PACKAGE_NAME}}
+
+# Run tests
+
+{{PACKAGE_MANAGER}} test --filter={{PACKAGE_NAME}}
+\`\`\`
+```
+
+## Code Comments Standards
+
+### When to Comment
+
+**Comment WHY, not WHAT:**
+
+```{{FILE_EXTENSION}}
+// ❌ BAD - Describes what (obvious from code)
+// Loop through users and check each one
+for (const user of users) { ... }
+
+// ✅ GOOD - Explains why
+// Process users in batches to avoid memory issues with large datasets
+for (const batch of chunk(users, 100)) { ... }
+```
+
+### File Headers
+
+```{{FILE_EXTENSION}}
+/**
+ * {{COMPONENT_NAME}}
+ *
+ * Purpose: Brief description of the file's responsibility
+ *
+ * Dependencies:
+ * - @{{PROJECT_NAME}}/ui: For base components
+ * - @{{PROJECT_NAME}}/api: For data fetching
+ *
+ * @see docs/architecture/components.md
+ */
+```
+
+### Function Documentation
+
+```typescript
+/**
+ * Calculates engagement score based on user activity.
+ *
+ * Uses a weighted algorithm favoring recent activity.
+ *
+ * @param userId - User identifier
+ * @param options - Calculation options
+ * @returns Score 0-100, null if insufficient data
+ *
+ * @example
+ * const score = await calculateScore('user-123', { days: 7 });
+ *
+ * @throws {UserNotFoundError} When user doesn't exist
+ */
+async function calculateEngagementScore(
+	userId: string,
+	options?: ScoreOptions,
+): Promise<number | null>;
+```
+
+### Comment Tags
+
+| Tag              | Usage                           |
+| ---------------- | ------------------------------- |
+| `TODO(username)` | Planned improvements with owner |
+| `FIXME`          | Known issues to address         |
+| `HACK`           | Temporary workarounds           |
+| `NOTE`           | Important context               |
+| `SECURITY`       | Security-sensitive code         |
+| `DEPRECATED`     | Code to be removed              |
+
+## Architectural Decision Records
+
+### ADR Template
+
+Location: `docs/architecture/decisions/ADR-NNN-title.md`
+
+```markdown
+# ADR-001: {{DECISION_TITLE}}
+
+## Status
+
+Accepted | Proposed | Deprecated | Superseded by ADR-XXX
+
+## Context
+
+What problem are we solving? What constraints exist?
+
+## Decision
+
+What did we decide? Be specific about the approach.
+
+## Consequences
+
+### Positive
+
+- Benefit 1
+- Benefit 2
+
+### Negative
+
+- Tradeoff 1
+- Tradeoff 2
+
+### Neutral
+
+- Related change
+
+## References
+
+- [Related ADR](./ADR-000-related.md)
+- [External resource](https://example.com)
+```
+
+### When to Write ADRs
+
+- Choosing between technologies
+- Establishing architecture patterns
+- Making breaking changes
+- Security-related decisions
+- Significant dependency changes
+
+## Changelog Standards
+
+### Format (Keep a Changelog)
+
+```markdown
+# Changelog
+
+Format based on [Keep a Changelog](https://keepachangelog.com/).
+
+## [Unreleased]
+
+### Added
+
+- New feature description (#PR)
+
+### Changed
+
+- Modified behavior (#PR)
+
+### Fixed
+
+- Bug fix description (#PR)
+
+## [1.2.0] - 2026-01-26
+
+### Added
+
+- Feature description
+```
+
+### Commit Messages
+
+```
+type(scope): subject
+
+body (optional)
+
+footer (optional)
+```
+
+Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
+
+## Cross-Package Documentation
+
+### Linking Between Docs
+
+```markdown
+<!-- From app README to package -->
+
+See [@{{PROJECT_NAME}}/ui](../../packages/ui/README.md) for component docs.
+
+<!-- From package to architecture -->
+
+See [Component Architecture](../../docs/architecture/components.md).
+```
+
+### API Documentation
+
+For shared packages, maintain:
+
+```
+packages/{{PACKAGE_NAME}}/
+├── README.md              # Usage guide
+├── docs/
+│   ├── api.md             # Full API reference
+│   └── examples/          # Code examples
+└── CHANGELOG.md           # Package changelog
+```
+
+## Documentation Quality Checklist
+
+### Before Merging
+
+- [ ] README updated if behavior changed
+- [ ] Public APIs have JSDoc/docstrings
+- [ ] Complex logic has explanatory comments
+- [ ] Breaking changes documented in CHANGELOG
+- [ ] New features have usage examples
+- [ ] Links are not broken
+
+### Review Criteria
+
+- [ ] Documentation matches implementation
+- [ ] Examples are copy-paste ready
+- [ ] Consistent terminology used
+- [ ] Screenshots current (if applicable)
+
+## Related Skills
+
+- See `.agents/skills/writing-skills/` for prompt writing
+- See `.agents/skills/writing-plans/` for feature planning

package/src/monorepo/.agents/skills/receiving-code-review/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: receiving-code-review
+description: Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation
+---
+
+# Code Review Reception
+
+## Overview
+
+Code review requires technical evaluation, not emotional performance.
+
+**Core principle:** Verify before implementing. Ask before assuming. Technical correctness over social comfort.
+
+## The Response Pattern
+
+```
+WHEN receiving code review feedback:
+
+1. READ: Complete feedback without reacting
+2. UNDERSTAND: Restate requirement in own words (or ask)
+3. VERIFY: Check against codebase reality
+4. EVALUATE: Technically sound for THIS codebase?
+5. RESPOND: Technical acknowledgment or reasoned pushback
+6. IMPLEMENT: One item at a time, test each
+```
+
+## Forbidden Responses
+
+**NEVER:**
+- "You're absolutely right!" (explicit CLAUDE.md violation)
+- "Great point!" / "Excellent feedback!" (performative)
+- "Let me implement that now" (before verification)
+
+**INSTEAD:**
+- Restate the technical requirement
+- Ask clarifying questions
+- Push back with technical reasoning if wrong
+- Just start working (actions > words)
+
+## Handling Unclear Feedback
+
+```
+IF any item is unclear:
+  STOP - do not implement anything yet
+  ASK for clarification on unclear items
+
+WHY: Items may be related. Partial understanding = wrong implementation.
+```
+
+**Example:**
+```
+your human partner: "Fix 1-6"
+You understand 1,2,3,6. Unclear on 4,5.
+
+❌ WRONG: Implement 1,2,3,6 now, ask about 4,5 later
+✅ RIGHT: "I understand items 1,2,3,6. Need clarification on 4 and 5 before proceeding."
+```
+
+## Source-Specific Handling
+
+### From your human partner
+- **Trusted** - implement after understanding
+- **Still ask** if scope unclear
+- **No performative agreement**
+- **Skip to action** or technical acknowledgment
+
+### From External Reviewers
+```
+BEFORE implementing:
+  1. Check: Technically correct for THIS codebase?
+  2. Check: Breaks existing functionality?
+  3. Check: Reason for current implementation?
+  4. Check: Works on all platforms/versions?
+  5. Check: Does reviewer understand full context?
+
+IF suggestion seems wrong:
+  Push back with technical reasoning
+
+IF can't easily verify:
+  Say so: "I can't verify this without [X]. Should I [investigate/ask/proceed]?"
+
+IF conflicts with your human partner's prior decisions:
+  Stop and discuss with your human partner first
+```
+
+**your human partner's rule:** "External feedback - be skeptical, but check carefully"
+
+## YAGNI Check for "Professional" Features
+
+```
+IF reviewer suggests "implementing properly":
+  grep codebase for actual usage
+
+  IF unused: "This endpoint isn't called. Remove it (YAGNI)?"
+  IF used: Then implement properly
+```
+
+**your human partner's rule:** "You and reviewer both report to me. If we don't need this feature, don't add it."
+
+## Implementation Order
+
+```
+FOR multi-item feedback:
+  1. Clarify anything unclear FIRST
+  2. Then implement in this order:
+     - Blocking issues (breaks, security)
+     - Simple fixes (typos, imports)
+     - Complex fixes (refactoring, logic)
+  3. Test each fix individually
+  4. Verify no regressions
+```
+
+## When To Push Back
+
+Push back when:
+- Suggestion breaks existing functionality
+- Reviewer lacks full context
+- Violates YAGNI (unused feature)
+- Technically incorrect for this stack
+- Legacy/compatibility reasons exist
+- Conflicts with your human partner's architectural decisions
+
+**How to push back:**
+- Use technical reasoning, not defensiveness
+- Ask specific questions
+- Reference working tests/code
+- Involve your human partner if architectural
+
+**Signal if uncomfortable pushing back out loud:** "Strange things are afoot at the Circle K"
+
+## Acknowledging Correct Feedback
+
+When feedback IS correct:
+```
+✅ "Fixed. [Brief description of what changed]"
+✅ "Good catch - [specific issue]. Fixed in [location]."
+✅ [Just fix it and show in the code]
+
+❌ "You're absolutely right!"
+❌ "Great point!"
+❌ "Thanks for catching that!"
+❌ "Thanks for [anything]"
+❌ ANY gratitude expression
+```
+
+**Why no thanks:** Actions speak. Just fix it. The code itself shows you heard the feedback.
+
+**If you catch yourself about to write "Thanks":** DELETE IT. State the fix instead.
+
+## Gracefully Correcting Your Pushback
+
+If you pushed back and were wrong:
+```
+✅ "You were right - I checked [X] and it does [Y]. Implementing now."
+✅ "Verified this and you're correct. My initial understanding was wrong because [reason]. Fixing."
+
+❌ Long apology
+❌ Defending why you pushed back
+❌ Over-explaining
+```
+
+State the correction factually and move on.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Performative agreement | State requirement or just act |
+| Blind implementation | Verify against codebase first |
+| Batch without testing | One at a time, test each |
+| Assuming reviewer is right | Check if breaks things |
+| Avoiding pushback | Technical correctness > comfort |
+| Partial implementation | Clarify all items first |
+| Can't verify, proceed anyway | State limitation, ask for direction |
+
+## Real Examples
+
+**Performative Agreement (Bad):**
+```
+Reviewer: "Remove legacy code"
+❌ "You're absolutely right! Let me remove that..."
+```
+
+**Technical Verification (Good):**
+```
+Reviewer: "Remove legacy code"
+✅ "Checking... build target is 10.15+, this API needs 13+. Need legacy for backward compat. Current impl has wrong bundle ID - fix it or drop pre-13 support?"
+```
+
+**YAGNI (Good):**
+```
+Reviewer: "Implement proper metrics tracking with database, date filters, CSV export"
+✅ "Grepped codebase - nothing calls this endpoint. Remove it (YAGNI)? Or is there usage I'm missing?"
+```
+
+**Unclear Item (Good):**
+```
+your human partner: "Fix items 1-6"
+You understand 1,2,3,6. Unclear on 4,5.
+✅ "Understand 1,2,3,6. Need clarification on 4 and 5 before implementing."
+```
+
+## GitHub Thread Replies
+
+When replying to inline review comments on GitHub, reply in the comment thread (`gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies`), not as a top-level PR comment.
+
+## The Bottom Line
+
+**External feedback = suggestions to evaluate, not orders to follow.**
+
+Verify. Question. Then implement.
+
+No performative agreement. Technical rigor always.