Ness.OS Development Cursor Rules
This skill provides comprehensive development guidelines and architectural rules for the Ness.OS project, ensuring consistency across documentation, code structure, and integration patterns.
What This Skill Does
Enforces project-specific conventions and best practices for Ness.OS development, including:
Project architecture and documentation structureSeparation of application agents vs AI playbooksSchema alignment and migration planningGitHub integration patternsFrontend conventions (Next.js)Testing, security, and tooling standardsInstructions
When working on the Ness.OS project, follow these guidelines:
1. Documentation Structure
The project maintains a structured documentation system in `.context/docs/`:
**Core Guides:**
`project-overview.md` — High-level project summary and goals`architecture.md` — System architecture, ADRs, service boundaries`development-workflow.md` — Branching strategy, CI/CD, contributing guidelines`testing-strategy.md` — Test configurations, CI gates, flaky test tracking`glossary.md` — Business terminology, user personas, domain concepts`data-flow.md` — System diagrams, integration specs, data flows`security.md` — Authentication model, secrets management, compliance`tooling.md` — CLI scripts, IDE configurations, automation workflows**When updating documentation:**
Keep guides in sync with code changesUse the document map structure for consistencyAuto-generate documentation index using the established toolingPlace living documentation in `docs/`, architectural docs in `.context/docs/`2. Agent Separation Convention
**CRITICAL:** Do not mix application agents with AI playbook roles.
**Application Agents (10 product agents):** Core business logic agents that power the Ness.OS product**AI Playbook Roles:** Development assistance roles in `.context/agents/` for AI-driven workflowsReference: `docs/context-separation.md`
**When creating new agents:**
Clearly identify whether it's a product feature agent or a development playbook rolePlace product agents in application code directoriesPlace AI playbooks in `.context/agents/`Document the separation in the glossary3. Schema Alignment & Migration Planning
Follow the schema adjustment plan outlined in `docs/plan-ajuste-schema-ao-projeto.md`:
**Current State:**
`fin` schema at version `001` (complete)**Planned Schemas:**
`ops` — Operations and infrastructure`growth` — Marketing and growth metrics`jur` — Legal and compliance`gov` — Governance and administration`people` — HR and team management`kb` — Knowledge base**When working with schemas:**
Follow migration versioning conventionsAlign schema changes with AI-context requirementsDocument breaking changes in architecture notesUpdate data flow diagrams when adding new schemas4. GitHub Integration Patterns
Follow the integration plan in `docs/plan-github-novos-passos-integracao.md`:
**Frontend Structure (Next.js):**
`src/app/` — App router pages and routes`src/components/` — React components`src/lib/` — Shared utilities and libraries**When integrating features:**
Place API routes in `src/app/api/`Use server components by defaultClient components must use `'use client'` directiveIntegrate with existing plans and AI-contextFollow the established component organization5. Development Workflow
**Repository Structure:**
`ARCHITECTURE.md` — High-level architecture overview`docs/` — Living documentation (updated frequently)`.context/docs/` — Stable architectural documentation`README.md` — Project entry point**Branching & CI:**
Follow branching rules in `development-workflow.md`Ensure CI gates pass before mergingReference the CI configuration for build requirements6. Testing Standards
Refer to `testing-strategy.md` for:
Test configuration patternsCI gate requirementsKnown flaky test suitesTesting tool recommendations**When adding tests:**
Follow existing test structure conventionsDocument any flaky tests discoveredUpdate testing strategy docs if introducing new patterns7. Security & Compliance
Consult `security.md` for:
Authentication and authorization modelsSecrets management practicesCompliance requirementsSecurity review checklists**When handling sensitive data:**
Never commit secrets to version controlFollow the documented auth patternsUpdate security notes if introducing new auth flows8. Tooling & Productivity
Reference `tooling.md` for:
CLI scripts and automationIDE configuration recommendationsDevelopment workflow optimizations**When adding new tools:**
Document in the tooling guideProvide setup instructionsInclude usage examplesQ&A Reference
The project maintains Q&A documentation in `.context/qa/`:
`getting-started.md` — Setup and running instructions`project-structure.md` — Codebase organization explanationUsage Examples
**Example 1: Adding a new feature**
```
1. Review architecture.md for service boundaries
2. Check glossary.md for domain terminology
3. Follow development-workflow.md for branching
4. Implement in src/app/ or src/components/
5. Add tests following testing-strategy.md
6. Update relevant documentation in docs/
7. Submit PR following contributing guidelines
```
**Example 2: Creating a new schema**
```
1. Check plan-ajuste-schema-ao-projeto.md for alignment
2. Follow migration versioning conventions
3. Update data-flow.md with new schema
4. Document in glossary.md if introducing domain concepts
5. Ensure AI-context integration if needed
```
**Example 3: Adding documentation**
```
1. Determine if it's living docs (docs/) or architectural (.context/docs/)
2. Follow the document map structure in README.md
3. Update the documentation index
4. Cross-reference related guides
5. Regenerate documentation index using tooling
```
Important Notes
**Documentation is auto-generated**: The `.context/docs/README.md` includes a timestamp showing last generation**Project type detection**: The Q&A README indicates project type (currently "unknown")**Convention over configuration**: Follow established patterns before introducing new ones**Keep docs in sync**: Update documentation alongside code changes**Separation is critical**: Always maintain the distinction between product agents and AI playbooksConstraints
All documentation must follow the established structureSchema changes require alignment with the migration planFrontend code must adhere to Next.js App Router conventionsSecurity patterns must not be violated without architectural reviewAgent separation convention is non-negotiable