nitm-ai-dev-toolkit 3.0.15

package/src/monorepo/README.md

@@ -0,0 +1,182 @@
+# {{PROJECT_NAME}}
+
+{{PROJECT_DESCRIPTION}}
+
+## Common Placeholders
+
+Templates use `{{PLACEHOLDER}}` syntax (SCREAMING_SNAKE_CASE). The most common placeholders:
+
+| Placeholder | Description |
+| --- | --- |
+| `{{PROJECT_NAME}}` | Project name |
+| `{{FRAMEWORK}}` | Primary framework (Next.js, Nuxt, Laravel, Django, etc.) |
+| `{{LANGUAGE}}` | Programming language (TypeScript, PHP, Python, C#, etc.) |
+| `{{PACKAGE_MANAGER}}` | Package manager (npm, pnpm, composer, pip, etc.) |
+| `{{DEV_PORT}}` | Development server port |
+| `{{DEPLOY_PLATFORM}}` | Deployment target |
+| `{{ISSUE_TRACKER}}` | Issue tracker (Jira, Linear, GitHub Issues) |
+| `{{ISSUE_ID}}` | Issue or ticket identifier |
+| `{{FEATURE_NAME}}` | Feature name |
+| `{{PROJECT_DESCRIPTION}}` | Short project description |
+| `{{DEFAULT_BRANCH}}` | Default git branch (e.g., main) |
+| `{{REPO_URL}}` | Repository URL |
+| `{{SRC_DIR}}` | Source directory |
+| `{{TEST_DIR}}` | Test directory |
+| `{{FILE_EXTENSION}}` | Primary source file extension |
+| `{{APP_NAME_1}}` | First app name |
+| `{{APP_DIR}}` | App directory under apps/ |
+| `{{BUILD_SYSTEM}}` | Monorepo build system (Turborepo, Nx, etc.) |
+| `{{DOCS_APP}}` | Docs app name |
+| `{{PACKAGES_DIR}}` | Shared packages directory |
+
+Individual templates and skills may use additional placeholders; those are documented in the template's own header or README.
+
+## Monorepo Structure
+
+This is a monorepo managed with {{BUILD_SYSTEM}}.
+
+```
+{{PROJECT_NAME}}/
+├── apps/
+│   ├── {{APP_NAME_1}}/          # {{APP_1_DESCRIPTION}}
+│   └── {{APP_NAME_2}}/          # {{APP_2_DESCRIPTION}}
+├── packages/
+│   ├── {{PACKAGE_NAME_1}}/      # {{PACKAGE_1_DESCRIPTION}}
+│   ├── {{PACKAGE_NAME_2}}/      # {{PACKAGE_2_DESCRIPTION}}
+│   └── config/                  # Shared configuration
+├── {{MONOREPO_CONFIG}}          # Monorepo configuration
+└── package.json                 # Root workspace config
+```
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js {{NODE_VERSION}}
+- {{PACKAGE_MANAGER}}
+
+### Installation
+
+```bash
+# Clone the repository
+git clone {{REPO_URL}}
+cd {{PROJECT_NAME}}
+
+# Install dependencies
+{{PACKAGE_MANAGER}} install
+```
+
+### Development
+
+```bash
+# Run all apps in development mode
+{{PACKAGE_MANAGER}} dev
+
+# Run specific app
+{{PACKAGE_MANAGER}} dev --filter={{APP_NAME_1}}
+
+# Build all packages
+{{PACKAGE_MANAGER}} build
+
+# Run tests
+{{PACKAGE_MANAGER}} test
+```
+
+## Apps
+
+| App              | Description           | Port               |
+| ---------------- | --------------------- | ------------------ |
+| `{{APP_NAME_1}}` | {{APP_1_DESCRIPTION}} | {{APP_1_DEV_PORT}} |
+| `{{APP_NAME_2}}` | {{APP_2_DESCRIPTION}} | {{APP_2_DEV_PORT}} |
+
+## Packages
+
+| Package                                | Description                                 |
+| -------------------------------------- | ------------------------------------------- |
+| `@{{PROJECT_NAME}}/{{PACKAGE_NAME_1}}` | {{PACKAGE_1_DESCRIPTION}}                   |
+| `@{{PROJECT_NAME}}/{{PACKAGE_NAME_2}}` | {{PACKAGE_2_DESCRIPTION}}                   |
+| `@{{PROJECT_NAME}}/config`             | Shared ESLint, TypeScript, and build config |
+
+## Scripts
+
+```bash
+# Development
+{{PACKAGE_MANAGER}} dev                    # Start all apps
+{{PACKAGE_MANAGER}} dev --filter=<app>     # Start specific app
+
+# Building
+{{PACKAGE_MANAGER}} build                  # Build all packages
+{{PACKAGE_MANAGER}} build --filter=<app>   # Build specific app
+
+# Testing
+{{PACKAGE_MANAGER}} test                   # Run all tests
+{{PACKAGE_MANAGER}} test --filter=<app>    # Test specific app
+
+# Linting
+{{PACKAGE_MANAGER}} lint                   # Lint all packages
+{{PACKAGE_MANAGER}} format                 # Format code
+
+# Type checking
+{{PACKAGE_MANAGER}} check-types            # Type check all packages
+```
+
+## Monorepo Features
+
+- **Remote Caching**: Enabled via build system configuration
+- **Parallel Execution**: Tasks run in parallel when possible
+- **Incremental Builds**: Only rebuilds changed packages
+- **Task Dependencies**: Defined in monorepo config
+
+## Environment Variables
+
+Create `.env` files in each app directory:
+
+```bash
+# apps/{{APP_NAME_1}}/.env.local
+{{APP_1_ENV_EXAMPLE}}
+
+# apps/{{APP_NAME_2}}/.env.local
+{{APP_2_ENV_EXAMPLE}}
+```
+
+## Documentation
+
+- [AGENTS.md](AGENTS.md) - AI development context
+- [apps/{{APP_NAME_1}}/README.md](apps/{{APP_NAME_1}}/README.md) - App documentation
+- [packages/{{PACKAGE_NAME_1}}/README.md](packages/{{PACKAGE_NAME_1}}/README.md) - Package documentation
+
+## AI Instructions and Commands
+
+This monorepo includes AI instruction files to standardize development workflows across tools. The `.cursor/` and `.github/` folders define how AI assistants should analyze, plan, implement, and review changes across apps and packages.
+
+### Planning
+
+- `/specify` — Create or refine a feature specification.
+- `/plan` — Produce an implementation plan with steps and dependencies.
+- `/tasks` — Break work into actionable tasks.
+- `/assign-tasks` — Convert requirements into tickets in `{{ISSUE_TRACKER}}`.
+
+### Implementing
+
+- `/implement-feature` — Implement a feature from tasks/specs with validation.
+- `/implement-fixes` — Apply focused bug fixes with testing and PR notes.
+
+### Reviewing
+
+- `/review` — Run a structured code review checklist for changes.
+- `/review-pr` — Review pull requests with architecture, testing, and security checks.
+
+### Code Management
+
+- `/commit-push` — Create conventional commits and push safely to a feature branch.
+
+## Contributing
+
+1. Create a feature branch
+2. Make changes following project conventions
+3. Run `{{PACKAGE_MANAGER}} lint` and `{{PACKAGE_MANAGER}} test`
+4. Submit a pull request
+
+## License
+
+{{LICENSE_TYPE}}

package/src/monorepo/apps/app-template/AGENTS.md

@@ -0,0 +1,169 @@
+# AGENTS.md - {{APP_NAME}} App
+
+**Type:** {{APP_TYPE}}
+**Framework:** {{APP_FRAMEWORK}}
+**Port:** {{APP_DEV_PORT}}
+
+## Overview
+
+{{APP_DESCRIPTION}}
+
+## Structure
+
+```
+apps/{{APP_NAME}}/
+├── src/
+│   ├── {{APP_SRC_STRUCTURE}}
+├── tests/
+│   ├── unit/
+│   ├── integration/
+│   └── e2e/
+├── public/
+├── package.json
+└── AGENTS.md
+```
+
+## Tech Stack
+
+- **Framework:** {{APP_FRAMEWORK}}
+- **Language:** TypeScript
+- **Styling:** {{APP_STYLING}}
+- **State:** {{APP_STATE_MANAGEMENT}}
+- **Testing:** {{TEST_FRAMEWORK}}
+
+## Commands
+
+```bash
+# Development
+{{PACKAGE_MANAGER}} dev --filter={{APP_NAME}}
+
+# Build
+{{PACKAGE_MANAGER}} build --filter={{APP_NAME}}
+
+# Test
+{{PACKAGE_MANAGER}} test --filter={{APP_NAME}}
+
+# Lint
+{{PACKAGE_MANAGER}} lint --filter={{APP_NAME}}
+```
+
+## Component Patterns
+
+```{{APP_COMPONENT_EXTENSION}}
+{{APP_COMPONENT_TEMPLATE}}
+```
+
+## State Management
+
+```typescript
+{
+	{
+		APP_STATE_PATTERN;
+	}
+}
+```
+
+## API Integration
+
+```typescript
+{
+	{
+		APP_API_PATTERN;
+	}
+}
+```
+
+## Shared Package Usage
+
+```typescript
+// Import from shared packages
+import { Component } from "@{{PROJECT_NAME}}/ui";
+import { formatDate } from "@{{PROJECT_NAME}}/utils";
+import type { User } from "@{{PROJECT_NAME}}/types";
+```
+
+## Environment Variables
+
+```bash
+# .env.local
+{{APP_ENV_EXAMPLE}}
+```
+
+## Testing
+
+### Unit Tests
+
+```typescript
+{
+	{
+		APP_UNIT_TEST_EXAMPLE;
+	}
+}
+```
+
+### E2E Tests
+
+```typescript
+{
+	{
+		APP_E2E_TEST_EXAMPLE;
+	}
+}
+```
+
+## Deployment
+
+- **Platform:** {{APP_DEPLOY_PLATFORM}}
+- **Command:** `{{PACKAGE_MANAGER}} deploy:{{APP_NAME}}`
+
+## Clarification & Alignment Guidelines
+
+### 1. Proactive Clarification
+
+- **Identify Ambiguity**: Stop and ask if a task lacks clear acceptance criteria, inputs, or expected outputs.
+- **Resolve Conflicts**: Flag conflicting instructions between the user prompt, existing code, and documentation before writing code.
+- **Expose Assumptions**: State your assumptions clearly and ask for validation before proceeding with high-impact changes.
+
+### 2. Technical Validation & Alternatives
+
+- **Propose Better Paths**: Suggest a simpler, more performant, or more idiomatic alternative if you see a better way to solve the problem.
+- **Flag Code Smells**: Alert the team if the requested changes introduce technical debt, anti-patterns, or break existing architectural rules.
+- **Check Dependencies**: Ask for verification if a task requires adding new third-party libraries or upgrading existing versions.
+
+### 3. Scope & Edge Case Management
+
+- **Surface Edge Cases**: List potential failures, null states, or security risks you discover, and ask how to handle them.
+- **Prevent Scope Creep**: Ask for permission before modifying files or logic outside the explicit scope of the assigned task.
+- **Clarify Breakages**: Warn the user immediately if a requested change will intentionally break backward compatibility or existing APIs.
+
+### 4. How to Ask Questions (Response Formatting)
+
+When stopping to ask a question, do not just post an open-ended block of text. Format your query using one of these two structures:
+
+- **Structured Multiple-Choice**: For architectural, design, or logic choices, provide a numbered list of distinct options. Include a brief pro/con or trade-off for each path so the user can quickly respond with just a number (e.g., "Go with Option 2").
+- **Targeted Text Input**: For missing data, API endpoints, or environment variables, provide a clear, pre-formatted Markdown template or fill-in-the-blank block. The user should be able to copy, fill out, and return it with minimal friction.
+
+## Documentation Requirements
+
+Documentation updates are **mandatory before committing**. See the root [`.github/instructions/documentation.instructions.md`](../../.github/instructions/documentation.instructions.md) for the full pre-commit checklist and AI agent directives.
+
+**Quick summary:**
+
+- Ensure feature spec/plan exists and is current in `docs/features/`
+- Update `docs/api/` for any API surface changes
+- Update `README.md` for setup, command, or env var changes
+- If a `docs` app exists in the monorepo, update its content pages and navigation
+
+### If This App IS the Docs App
+
+If `{{APP_NAME}}` is the dedicated documentation site for this monorepo:
+
+- Every new or changed feature in **any** app or package requires a corresponding page update here
+- Register new pages in the sidebar/navigation config
+- Preview locally before committing: `{{PACKAGE_MANAGER}} dev --filter={{APP_NAME}}`
+- Include docs-app changes in the same commit/PR as the code they document
+
+## Related
+
+- [Root AGENTS.md](../../AGENTS.md) - Monorepo context
+- [README.md](README.md) - App documentation

package/src/monorepo/apps/app-template/README.md

@@ -0,0 +1,77 @@
+# {{APP_NAME}}
+
+{{APP_DESCRIPTION}}
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js {{NODE_VERSION}}
+- {{PACKAGE_MANAGER}}
+
+### Development
+
+```bash
+# From monorepo root
+{{PACKAGE_MANAGER}} dev --filter={{APP_NAME}}
+
+# Or from this directory
+{{PACKAGE_MANAGER}} dev
+```
+
+Visit [http://localhost:{{APP_DEV_PORT}}](http://localhost:{{APP_DEV_PORT}})
+
+### Building
+
+```bash
+{{PACKAGE_MANAGER}} build --filter={{APP_NAME}}
+```
+
+### Testing
+
+```bash
+# Unit tests
+{{PACKAGE_MANAGER}} test --filter={{APP_NAME}}
+
+# E2E tests
+{{PACKAGE_MANAGER}} test:e2e --filter={{APP_NAME}}
+```
+
+## Structure
+
+```
+{{APP_NAME}}/
+├── src/
+│   ├── {{APP_SRC_STRUCTURE}}
+├── tests/
+├── public/
+└── package.json
+```
+
+## Shared Packages
+
+This app uses the following shared packages:
+
+- `@{{PROJECT_NAME}}/{{PACKAGE_NAME_1}}` - {{PACKAGE_1_DESCRIPTION}}
+- `@{{PROJECT_NAME}}/{{PACKAGE_NAME_2}}` - {{PACKAGE_2_DESCRIPTION}}
+
+## Environment Variables
+
+Create a `.env.local` file:
+
+```bash
+{{APP_ENV_EXAMPLE}}
+```
+
+## Deployment
+
+Deployed to {{APP_DEPLOY_PLATFORM}}:
+
+```bash
+{{PACKAGE_MANAGER}} deploy:{{APP_NAME}}
+```
+
+## Related
+
+- [Monorepo README](../../README.md)
+- [AGENTS.md](AGENTS.md) - AI development context

package/src/monorepo/docs/api/README.md

@@ -0,0 +1,82 @@
+# API Documentation
+
+This folder contains API specifications and documentation.
+
+## Structure
+
+```
+api/
+├── README.md           # This file
+├── overview.md         # API overview and conventions
+├── authentication.md   # Authentication details
+└── endpoints/          # Individual endpoint documentation
+    ├── users.md
+    ├── posts.md
+    └── ...
+```
+
+## Documentation Standards
+
+### Endpoint Documentation
+
+Each endpoint should document:
+
+- **HTTP Method and Path**
+- **Description**
+- **Authentication requirements**
+- **Request parameters** (path, query, body)
+- **Response format**
+- **Error responses**
+- **Examples**
+
+### Example Format
+
+```markdown
+## GET /api/{{RESOURCE}}/:id
+
+Retrieve a single {{RESOURCE}} by ID.
+
+### Authentication
+
+Required: Bearer token
+
+### Parameters
+
+| Name | Type   | In   | Required | Description         |
+| ---- | ------ | ---- | -------- | ------------------- |
+| id   | string | path | Yes      | The {{RESOURCE}} ID |
+
+### Response
+
+**Success (200)**
+\`\`\`json
+{
+"id": "123",
+"name": "Example",
+"createdAt": "2026-01-01T00:00:00Z"
+}
+\`\`\`
+
+**Error (404)**
+\`\`\`json
+{
+"error": "Not found",
+"message": "{{RESOURCE}} with id '123' not found"
+}
+\`\`\`
+```
+
+## API Versioning
+
+Document the API versioning strategy:
+
+- URL versioning: `/api/v1/resource`
+- Header versioning: `API-Version: 1`
+- Query versioning: `/api/resource?version=1`
+
+## OpenAPI/Swagger
+
+If using OpenAPI, place the specification file here:
+
+- `openapi.yaml` or `openapi.json`
+- Link to interactive documentation (e.g., Swagger UI)

package/src/monorepo/docs/architecture/README.md

@@ -0,0 +1,56 @@
+# Architecture Decision Records
+
+This folder contains Architecture Decision Records (ADRs) documenting significant technical decisions made in this project.
+
+## What is an ADR?
+
+An ADR is a short document describing a significant software design choice along with its context and consequences.
+
+## Structure
+
+```
+architecture/
+├── 0001-initial-architecture.md
+├── 0002-database-choice.md
+├── 0003-api-design.md
+└── README.md
+```
+
+## Creating an ADR
+
+1. Copy the template:
+
+   ```bash
+   cp templates/adr.template.md docs/architecture/{{ADR_NUMBER}}-{{DECISION_TITLE}}.md
+   ```
+
+2. Fill in the template with:
+   - Context and problem statement
+   - Considered options
+   - Decision outcome and rationale
+   - Consequences
+
+## Naming Convention
+
+ADRs are numbered sequentially: `NNNN-short-title.md`
+
+- `0001-initial-project-structure.md`
+- `0002-authentication-strategy.md`
+- `0003-database-migration-approach.md`
+
+## Status
+
+ADRs can have the following statuses:
+
+- **Proposed** - Under discussion
+- **Accepted** - Decision made and being implemented
+- **Deprecated** - No longer relevant
+- **Superseded** - Replaced by another ADR
+
+## Index
+
+<!-- Add your ADRs here as you create them -->
+
+| ADR  | Title                                          | Status   | Date     |
+| ---- | ---------------------------------------------- | -------- | -------- |
+| 0001 | [Example Decision](./0001-example-decision.md) | Accepted | {{DATE}} |

package/src/monorepo/docs/features/README.md

@@ -0,0 +1,82 @@
+# Features Documentation
+
+This folder contains documentation for all features implemented in this project.
+
+## Structure
+
+Each feature gets its own folder named after the issue ID and feature name:
+
+```
+features/
+├── {{ISSUE_ID}}-FEATURE-NAME/
+│   ├── spec.md       # Functional specification
+│   ├── plan.md       # Implementation plan
+│   └── [optional]    # Additional files (diagrams, examples)
+└── README.md         # This file
+```
+
+## Creating Feature Documentation
+
+### 1. Create Feature Folder
+
+```bash
+mkdir -p docs/features/{{ISSUE_ID}}-FEATURE-NAME
+```
+
+### 2. Generate Specification
+
+Use the `/spec` command or copy the template:
+
+```bash
+cp templates/feature-spec.template.md docs/features/{{ISSUE_ID}}-FEATURE-NAME/spec.md
+```
+
+### 3. Generate Implementation Plan
+
+Use the `/plan` command or copy the template:
+
+```bash
+cp templates/feature-plan.template.md docs/features/{{ISSUE_ID}}-FEATURE-NAME/plan.md
+```
+
+### 4. Update During Implementation
+
+Keep documentation updated as:
+
+- Requirements change
+- Implementation details emerge
+- New decisions are made
+
+## Naming Conventions
+
+**Folder names** should follow this pattern:
+
+- `{{ISSUE_ID}}-FEATURE-NAME`
+- Issue ID from your issue tracker (e.g., `ISSUE-123`, `JIRA-456`)
+- Feature name in kebab-case (e.g., `user-authentication`, `data-export`)
+
+**Examples:**
+
+- `ISSUE-123-user-authentication/`
+- `JIRA-456-data-export-api/`
+- `GH-789-dark-mode-support/`
+
+## Index of Features
+
+<!-- Auto-generated or manually maintained list of features -->
+
+### Active Features
+
+- [{{ISSUE_ID}}-FEATURE-NAME]({{ISSUE_ID}}-FEATURE-NAME/) - Brief description
+
+### Completed Features
+
+- [{{ISSUE_ID}}-COMPLETED-FEATURE]({{ISSUE_ID}}-COMPLETED-FEATURE/) - Brief description
+
+### Deprecated Features
+
+- [{{ISSUE_ID}}-DEPRECATED-FEATURE]({{ISSUE_ID}}-DEPRECATED-FEATURE/) - Deprecated on {{DATE}}
+
+---
+
+**Last Updated**: {{DATE}}