agent-ctx 1.0.0

package/src/templates/en/base/_project_state.md

@@ -0,0 +1,48 @@
+# Project State (Memory)
+
+> This file is updated manually so the AI knows where it left off in the last session.
+> **Last updated:** [DATE]
+
+## Current Context
+
+[Briefly describe what phase the project is in: MVP, active development, maintenance, etc.]
+
+## Recently Completed
+
+- [x] Completed task 1
+- [x] Completed task 2
+- [x] Completed task 3
+
+## In Progress (Current Sprint)
+
+- [ ] Task in progress 1
+- [ ] Task in progress 2
+- [ ] Task in progress 3
+
+## Coming Up Next
+
+- [ ] Pending task 1
+- [ ] Pending task 2
+
+## Known Bugs / Technical Debt
+
+| Bug/Issue | Priority | Notes |
+|-----------|----------|-------|
+| Bug description | High/Medium/Low | Additional context |
+
+## Important Decisions
+
+- **Decision 1**: [What was decided and why]
+- **Decision 2**: [What was decided and why]
+
+## Notes for Next Session
+
+> Write here anything important the AI should know before starting to work:
+
+- Note 1
+- Note 2
+
+## Current Restrictions
+
+- Do not modify [X] because [reason]
+- Avoid [Y] until [condition]

package/src/templates/en/base/_rule.md

@@ -0,0 +1,56 @@
+---
+type: rule-template
+target: .context/rules/{name}.md
+---
+
+# AI Guide
+
+You are helping the user create a new coding rule/standard document. Follow these steps:
+1. Ask the user about the specific rule or standard they want to document
+2. Gather examples of correct and incorrect usage
+3. Fill in the template below with the information
+
+# Questions to Ask
+
+1. What is the name/title of this rule?
+2. What problem does this rule solve or prevent?
+3. What are the specific requirements or constraints?
+4. Can you provide examples of correct usage?
+5. Can you provide examples of what to avoid?
+6. Are there any exceptions to this rule?
+
+# Template Output
+
+```markdown
+# ⚖️ Rule: {name}
+
+> {brief description of the rule}
+
+## Why this rule exists
+
+{Explain the problem this rule prevents or the benefit it provides}
+
+## Requirements
+
+- {Requirement 1}
+- {Requirement 2}
+- {Requirement 3}
+
+## ✅ Correct Examples
+
+{code or examples showing correct usage}
+
+## ❌ Incorrect Examples
+
+{code or examples showing what to avoid}
+
+## Exceptions
+
+{List any valid exceptions to this rule, or "No exceptions" if none}
+
+## Enforcement
+
+- [ ] Linter rule: {rule name if applicable}
+- [ ] Code review checklist item
+- [ ] Automated test
+```

package/src/templates/en/base/_skill.md

@@ -0,0 +1,60 @@
+---
+name: skill-name
+description: Brief description of what this skill does and when to use it. Write in third person. Be specific about triggers and use cases.
+---
+
+# Skill Name
+
+Brief overview of the skill's purpose.
+
+## When to use
+
+- When the user asks for [specific task]
+- When [pattern or trigger] is detected
+- When working with [technology or domain]
+
+## Quick start
+
+Minimal example to get started immediately:
+
+```typescript
+// Concise, functional example
+import { example } from 'library';
+
+const result = example.process(input);
+```
+
+## Implementation steps
+
+1. **Step 1**: Brief description
+2. **Step 2**: Brief description
+3. **Step 3**: Brief description
+
+## Best practices
+
+### ✅ Do
+
+- Good practice 1
+- Good practice 2
+
+### ❌ Avoid
+
+- Anti-pattern 1
+- Anti-pattern 2
+
+## References
+
+- [Official docs](link)
+- [Best practices guide](link)
+
+## Verification checklist
+
+Copy and track progress:
+
+```
+- [ ] Dependencies installed
+- [ ] Configuration complete
+- [ ] Core logic implemented
+- [ ] Error handling added
+- [ ] Tests written
+```

package/src/templates/en/docs/doc-readme.md

@@ -0,0 +1,43 @@
+# 📚 External Documentation (Vendorizing)
+
+This folder contains documentation from external libraries and APIs so AI agents can consult it locally without depending on internet access.
+
+## 🎯 Purpose
+
+Many LLMs have outdated or limited knowledge about specific libraries. By placing documentation here, the agent can:
+
+1. Query up-to-date APIs
+2. View recent code examples
+3. Avoid suggesting deprecated code
+
+## 📥 What to place here?
+
+- **`llms.txt`**: Special documentation files for LLMs (e.g., `mui-llms.txt`, `vercel-llms.txt`)
+- **API References**: Documentation exports from APIs you use
+- **Changelogs**: Important change notes from critical dependencies
+- **Migration guides**: If you're migrating from one version to another
+
+## 💡 Examples of useful files
+
+```
+docs/
+├── mui-llms.txt           # Material UI docs for LLMs
+├── nextjs-app-router.md   # Next.js App Router guide
+├── prisma-schema-guide.md # Prisma schema reference
+├── tailwind-v4-changes.md # Tailwind v3 to v4 changes
+└── api-internal.md        # Your internal API documentation
+```
+
+## 🔍 How to get llms.txt
+
+Many modern libraries publish `.txt` files optimized for LLMs:
+
+- **Vercel**: `https://vercel.com/docs/llms.txt`
+- **Material UI**: Search in their repository
+- **Others**: Check `/llms.txt` or `/docs/llms.txt` on the official site
+
+## ⚠️ Notes
+
+- Keep only the essentials to avoid overloading the context
+- Update periodically when you update dependencies
+- Prioritize the libraries you use most in the project

package/src/templates/en/docs/mcp-readme.md

@@ -0,0 +1,21 @@
+# 🔌 Recommended MCP Servers
+
+This file maintains a list of recommended MCP (Model Context Protocol) servers for this project.
+Consistency in tooling across the team ensures better collaboration and AI assistance.
+
+## 📋 Server List
+
+| Server Name | Description | Purpose | Install Command / Source |
+|-------------|-------------|---------|--------------------------|
+| `context7`  | Documentation refresher | Keeps docs up-to-date in context | `npm install -g context7` |
+| `filesystem`| File System Access | Allow AI to read/write files | Native in most MCP clients |
+
+## 📦 How to Install
+
+Most MCP servers are installed via your editor's configuration (e.g., Cursor, VS Code).
+Refer to your editor's documentation on how to add these servers.
+
+## 📝 Notes
+
+- Add new servers here when the team agrees on a new standard tool.
+- Keep the installation commands updated.

package/src/templates/en/memory/active_context.md

@@ -0,0 +1,38 @@
+---
+name: active_context
+description: Current session state - dynamic, updates frequently during development
+---
+
+# Active Context
+
+> Last updated: [DATE]
+
+## Current Focus
+
+[What is currently being worked on]
+
+## Recent Changes
+
+- [Change 1]
+- [Change 2]
+
+## Open Questions
+
+- [ ] Question 1
+- [ ] Question 2
+
+## Blockers
+
+| Blocker | Impact | Status |
+|---------|--------|--------|
+| | | |
+
+## Next Steps
+
+1. [ ] Step 1
+2. [ ] Step 2
+3. [ ] Step 3
+
+---
+
+*This file is dynamically updated by the AI agent during development sessions.*

package/src/templates/en/memory/progress.md

@@ -0,0 +1,35 @@
+---
+name: progress
+description: Development progress tracking - dynamic, updates with each milestone
+---
+
+# Progress
+
+## Milestones
+
+### Phase 1: [Name]
+
+| Task | Status | Notes |
+|------|--------|-------|
+| | ⬜ Not Started | |
+| | 🔄 In Progress | |
+| | ✅ Complete | |
+
+## Changelog
+
+### [DATE]
+
+- Added: 
+- Changed: 
+- Fixed: 
+
+## Metrics
+
+| Metric | Value | Target |
+|--------|-------|--------|
+| Test Coverage | | |
+| Performance | | |
+
+---
+
+*This file tracks overall project progress and is updated by the AI agent.*

package/src/templates/en/memory/project_brief.md

@@ -0,0 +1,34 @@
+---
+name: project_brief
+description: Project vision and goals - static, rarely changes
+---
+
+# Project Brief
+
+## Vision
+
+[Describe the overall vision for this project]
+
+## Goals
+
+- [ ] Goal 1
+- [ ] Goal 2
+- [ ] Goal 3
+
+## Success Criteria
+
+1. [Criterion 1]
+2. [Criterion 2]
+
+## Constraints
+
+- [Technical constraint]
+- [Business constraint]
+- [Timeline constraint]
+
+## Stakeholders
+
+| Role | Name | Responsibility |
+|------|------|----------------|
+| Owner | | |
+| Developer | | |

package/src/templates/en/memory/tech_context.md

@@ -0,0 +1,44 @@
+---
+name: tech_context
+description: Technical stack and dependencies - semi-static, updates with major changes
+---
+
+# Technical Context
+
+## Stack
+
+| Layer | Technology | Version |
+|-------|------------|---------|
+| Language | | |
+| Framework | | |
+| Database | | |
+| Cache | | |
+| Hosting | | |
+
+## Dependencies
+
+### Production
+
+| Package | Purpose |
+|---------|---------|
+| | |
+
+### Development
+
+| Package | Purpose |
+|---------|---------|
+| | |
+
+## Architecture Decisions
+
+### [Decision 1]
+
+**Context:** 
+**Decision:** 
+**Consequences:** 
+
+## Integration Points
+
+- **API:** 
+- **External Services:** 
+- **Third-party:** 

package/src/templates/en/rules/rule-coding-standards.md

@@ -0,0 +1,22 @@
+# Coding Standards and Rules
+
+## 1. General Principles
+- **DRY (Don't Repeat Yourself):** Extract repeated logic to hooks or utilities.
+- **KISS (Keep It Simple, Stupid):** Prefer the most readable solution over the "clever" one.
+- **Composition:** Prefer small, composed components over monoliths.
+
+## 2. TypeScript & Typing
+- **Forbidden:** Using `any`. If you don't know the type, use `unknown` and do narrowing.
+- **Required:** Define interfaces/types for all component Props.
+- **Preference:** Use `type` for object definitions and `interface` if you need to extend them.
+
+## 3. Styles and Naming
+- **Components:** `PascalCase` (e.g., `UserProfile.tsx`).
+- **Functions/Variables:** `camelCase` (e.g., `getUserData`).
+- **Constants:** `UPPER_SNAKE_CASE` (e.g., `MAX_RETRY_COUNT`).
+- **CSS:** We use [Tailwind CSS]. Avoid inline styles (`style={{...}}`).
+
+## 4. Error Handling
+- Wrap async calls in `try/catch` blocks.
+- Use `ErrorBoundary` components for UI failures.
+- Never leave a `catch` empty. Log the error.

package/src/templates/en/skills/skill-agents.md

@@ -0,0 +1,74 @@
+---
+name: managing-agents
+description: Configure and update AGENTS.md context file for AI agents. Use when setting up agent context or modifying agent instructions.
+---
+
+# Managing Agents Context
+
+Configure the AGENTS.md file that orients AI agents to your project.
+
+## When to use
+
+- Setting up AI agent context for a new project
+- Updating agent instructions
+- Adding new knowledge sources for agents
+- Changing how agents should behave in your project
+
+## AGENTS.md Purpose
+
+The AGENTS.md file is the entry point for AI agents. It tells them:
+- What the project does
+- Where to find critical information
+- How to behave and what rules to follow
+
+## Standard Template
+
+```markdown
+# AI Agent Context
+
+You are a senior developer joining this project.
+Your goal is to help build, refactor, and maintain code following our architecture.
+
+## Knowledge Index
+
+Before writing code, load context from:
+
+- **Architecture:** `.context/architecture.md`
+- **Rules:** `.context/rules/coding-standards.md`
+- **Skills:** `.context/skills/`
+
+## Current State
+
+Check `.context/project_state.md` for current work status.
+```
+
+## Best Practices
+
+### ✅ Do
+
+- Keep AGENTS.md concise (under 50 lines)
+- Point to detailed files instead of duplicating content
+- Update when project structure changes
+- Include path to rules and conventions
+
+### ❌ Avoid
+
+- Putting detailed documentation in AGENTS.md
+- Outdated file paths
+- Generic instructions without project specifics
+- Conflicting information between files
+
+## Placement
+
+AGENTS.md should be at the project root:
+
+```
+project/
+├── AGENTS.md           # AI agent entry point
+├── .context/           # Detailed context
+│   ├── architecture.md
+│   ├── project_state.md
+│   ├── rules/
+│   └── skills/
+└── src/
+```

package/src/templates/en/skills/skill-api.md

@@ -0,0 +1,117 @@
+---
+name: api-design
+description: Design REST APIs with consistent patterns, proper HTTP status codes, and validation. Use when creating endpoints, handling errors, or implementing API versioning.
+---
+
+# API Design
+
+Patterns and best practices for designing REST APIs.
+
+## When to use
+
+- Designing REST endpoints
+- Handling errors consistently
+- Implementing API versioning
+- Adding request validation
+
+## REST Conventions
+
+### URL Structure
+
+```
+GET    /api/v1/users          # List users
+GET    /api/v1/users/:id      # Get user
+POST   /api/v1/users          # Create user
+PUT    /api/v1/users/:id      # Full update
+PATCH  /api/v1/users/:id      # Partial update
+DELETE /api/v1/users/:id      # Delete user
+```
+
+### Query Parameters
+
+```
+GET /api/v1/users?
+  page=1&                     # Pagination
+  limit=20&                   # Items per page
+  sort=createdAt:desc&        # Sorting
+  filter[status]=active       # Filters
+```
+
+## Standard Responses
+
+### Success (200, 201)
+
+```json
+{
+  "success": true,
+  "data": { "id": "123", "name": "John Doe" },
+  "meta": { "page": 1, "total": 100 }
+}
+```
+
+### Error (400, 404, 500)
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Email is required",
+    "details": [{ "field": "email", "message": "Required" }]
+  }
+}
+```
+
+## HTTP Status Codes
+
+| Code | Meaning | Usage |
+|------|---------|-------|
+| 200 | OK | Successful GET, PUT/PATCH |
+| 201 | Created | Successful POST |
+| 204 | No Content | Successful DELETE |
+| 400 | Bad Request | Validation failed |
+| 401 | Unauthorized | Not authenticated |
+| 403 | Forbidden | No permissions |
+| 404 | Not Found | Resource doesn't exist |
+| 500 | Server Error | Internal error |
+
+## Validation Example
+
+```typescript
+import { z } from 'zod';
+
+const userSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(2),
+  role: z.enum(['admin', 'user'])
+});
+
+export function validate(schema: z.ZodSchema) {
+  return (req, res, next) => {
+    const result = schema.safeParse(req.body);
+    if (!result.success) {
+      return res.status(400).json({
+        success: false,
+        error: { code: 'VALIDATION_ERROR', details: result.error.issues }
+      });
+    }
+    req.body = result.data;
+    next();
+  };
+}
+```
+
+## Best practices
+
+### ✅ Do
+
+- Always use HTTPS
+- Version in URL (`/api/v1/`)
+- Rate limiting
+- Consistent response format
+
+### ❌ Avoid
+
+- Verbs in URLs (`/getUsers`, `/deleteUser`)
+- Exposing internal IDs
+- Inconsistent response formats

package/src/templates/en/skills/skill-architecture.md

@@ -0,0 +1,87 @@
+---
+name: documenting-architecture
+description: Document project architecture, tech stack, and data flow. Use when setting up or updating architecture documentation.
+---
+
+# Documenting Architecture
+
+Create and maintain architecture documentation for AI agents and developers.
+
+## When to use
+
+- Starting a new project
+- Major tech stack changes
+- Adding new services or integrations
+- Onboarding new team members or AI agents
+
+## Architecture Document Structure
+
+```markdown
+# Project Architecture
+
+## Project Goal
+[2-3 lines describing the application purpose]
+
+## Tech Stack
+
+### Frontend
+| Technology | Version | Purpose |
+|------------|---------|---------|
+| React      | 18.x    | UI      |
+
+### Backend
+| Technology | Version | Purpose |
+|------------|---------|---------|
+| Node.js    | 20.x    | API     |
+
+## Directory Structure
+[Tree showing key directories]
+
+## Data Flow
+[Diagram or description of how data moves]
+
+## Environment Variables
+| Variable | Description | Required |
+|----------|-------------|----------|
+| API_KEY  | Service key | ✅       |
+```
+
+## Key Sections
+
+1. **Tech Stack**: All technologies with versions
+2. **Directory Structure**: Key folders and their purpose
+3. **Data Flow**: How data moves through the system
+4. **Environment Variables**: Required configuration
+5. **Critical Dependencies**: Important packages
+
+## Update Triggers
+
+Update architecture.md when:
+- Adding new frameworks or libraries
+- Changing directory structure
+- Adding new services or APIs
+- Modifying data flow
+
+## Best Practices
+
+### ✅ Do
+
+- Include specific versions
+- Document WHY not just WHAT
+- Keep current with actual codebase
+- Use tables for scanability
+
+### ❌ Avoid
+
+- Outdated version numbers
+- Missing critical integrations
+- Overly detailed (link to docs instead)
+- Implementation details (put in code comments)
+
+## File Location
+
+```
+project/
+└── .context/
+    └── architecture.md  # Main architecture doc
+```