SoftwareDesignProject

Imported from Ozia112/SoftwareDesignProject (AGENTS.md). Install upstream with npx skills add Ozia112/SoftwareDesignProject. Copyright stays with the author.

Repository Agent Search Policy

This repository uses a graph-first retrieval architecture for AI agents.

Agents MUST consult the repository graph before performing broad repository exploration.

Repository Graph

Generated files:

.graph/
  nodes.json
  edges.json
  adjacency.json
  reverse_adjacency.json
  search_index.json

Source of truth:

docs/soporte/mapa-nodos/nodos-docs.yaml

Graph generator:

build-graph.py

Python dependency:

python -m pip install -r requirements.txt

Default regeneration command:

python build-graph.py --pretty

Regenerate and commit .graph/ whenever the YAML source changes so agents can use the graph before broad exploration.

Graph Node ID Policy

Graph node IDs MUST represent stable repository artifacts, domains, decisions, requirements, use cases, or future source anchors.

Do not use temporary GitHub issue IDs, sprint ticket IDs, or task IDs as graph node IDs when the ticket only tracks the work needed to create or update an artifact. Those IDs become obsolete when the issue closes and pollute long-lived retrieval.

Use a stable artifact-oriented ID instead, for example:

• ARCH-ESTRUCTURA-CODIGO for docs/diseño/arquitectura/estructura-de-codigo.md
• DDR-* for design decisions
• CU-*, RF-*, RNF-*, RN-* for analysis artifacts
• SEQ-*, COLLAB-* for design diagrams
• SRC-ORQ-* for future source anchors

Issue IDs such as PSD-29 may be mentioned in PR descriptions, commit messages, changelog notes, or short document provenance when useful, but they SHOULD NOT be canonical graph IDs unless the issue itself creates a durable repository artifact whose stable identifier is intentionally the same as the issue.

When adding documentation created from an issue:

1. Choose the final artifact path first.
2. Choose a stable node ID based on the artifact role and location.
3. Add graph aliases for searchable concepts, not for transient ticket bookkeeping.
4. Link the issue in the PR or commit instead of making it part of the graph identity.

Mandatory Search Order

Before using grep, glob, recursive search, or broad document scanning, agents MUST follow this order:

1. .graph/search_index.json
2. .graph/nodes.json
3. .graph/adjacency.json
4. .graph/reverse_adjacency.json
5. Open only the most relevant documents
6. Use broad repository search only as last resort

If .graph/ is missing or stale, regenerate it with python build-graph.py --pretty before broad repository exploration.

Graph Query Strategy

Initial Resolution

Use search_index.json to resolve:

• IDs
• titles
• tags
• aliases
• paths
• node types
• statuses

Examples:

• "waitlist"
• "quota reservation"
• "commercial flow"
• "handoff"
• "tool calls"

Node Expansion

Use:

adjacency.json
reverse_adjacency.json

to expand:

• traces_to
• governed_by
• derives_from
• implements_future
• supports
• references
• contains

without opening files.

File Opening Policy

Do NOT open large amounts of documentation blindly.

Only open documentation files after:

1. Identifying relevant node IDs
2. Expanding graph relations
3. Reducing candidate artifacts

Repository Domain Model

Main repository areas:

GitHub Metadata Policy

For repository metadata hosted on GitHub, agents MUST use gh instead of web browsing or manual URL guessing.

Use gh for:

• Issues: gh issue view <number> --repo Ozia112/SoftwareDesignProject
• Issue search/listing: gh issue list --repo Ozia112/SoftwareDesignProject --search "<query>"
• Pull requests: gh pr view <number> --repo Ozia112/SoftwareDesignProject
• PR search/listing: gh pr list --repo Ozia112/SoftwareDesignProject --search "<query>"
• Remote commit search: gh search commits "<query>" --repo Ozia112/SoftwareDesignProject

Use local git only for local working tree state, local diffs, local history, and commit content already present in the clone.

Claude Code Architecture Context

Claude Code and other coding agents MUST align implementation with the documented design. If in doubt, read the corresponding CU before editing code.

Key Documentation Paths

Central Principle

The architectural principle is:

Bot emits signals. The system executes domain operations.

Local Spanish source:

El bot emite señales. El sistema ejecuta operaciones de dominio.

Implications:

• The Bot does not access the database.
• The Bot does not execute commercial transitions or operational mutations directly.
• The Bot emits signals and requests operations through tool calls.
• The orchestrator validates stage, consent, idempotency and tenant context before executing domain services.

Service to CU Map

This table is derived from DDR-02 and is the fast lookup for implementation ownership.

SOLID Applied to This Project

• SRP: each service owns one domain responsibility; do not mix conversation routing, scoring, quota and notifications in one class.
• OCP: add new tool calls, channels or event policies through new handlers/strategies instead of editing central conditionals everywhere.
• LSP: implementations of service interfaces must preserve documented CU preconditions and error semantics.
• ISP: keep DTOs and service interfaces narrow; a quota consumer should not depend on notification or tenant methods it does not use.
• DIP: orchestration depends on interfaces/ports for persistence, queues, LLM and channel adapters, not concrete SDKs or database clients.

Antipatterns to Avoid

• God services that combine bot loop, persistence, quota, scoring and notification logic.
• Putting domain decisions in the Bot instead of the orchestrator.
• Direct database access from Bot or LLM tool definitions.
• Updating commercial stage from EVT operational services.
• Treating score as a stage transition trigger.
• Duplicating business rules inside code without linking the RN/CU source.
• Creating DTOs inline inside services when they should be explicit contracts.

TypeScript and DTO Conventions

• Classes and interfaces: PascalCase.
• Methods, variables and properties: camelCase.
• Constants and enum-like literals exported as constants: UPPER_CASE.
• DTOs live under dto/ by service or module.
• Use explicit input/output DTOs for tool calls and service boundaries.
• Tool call results should use typed success/error envelopes consistent with DDR-02.

Testing Rule

Before merge, run:

pnpm test -- --coverage

Use pnpm for Node package scripts and dependency management. Do not use npm for this repository unless the user explicitly asks for it.

If the codebase does not yet contain a Node/NestJS test setup, state that clearly in the PR and verify the documentation graph instead.

Preferred Navigation

Requirements

Start from:

RF-*
RNF-*
RN-*

Use Cases

Start from:

CU-*

Design Decisions

Start from:

DDR-*

Sequence / Collaboration

Start from:

SEQ-*
COLLAB-*

Future Code Anchors

Start from:

SRC-ORQ-*

Future Source Code Policy

When src/ becomes populated:

1. Link source files to graph nodes
2. Maintain traceability:
   • requirement → use case → design → source
3. Avoid semantic drift between implementation and documentation

Agent Behavior Constraints

Agents SHOULD:

• minimize exploratory tool calls
• minimize broad text scanning
• prioritize graph traversal
• use repository traceability
• preserve architectural consistency

Agents SHOULD NOT:

• scan the repository recursively without graph consultation
• infer undocumented architecture
• bypass graph relationships
• ignore traceability links

Expected Workflow

Typical workflow:

search_index.json
    ↓
nodes.json
    ↓
adjacency expansion
    ↓
targeted document reads
    ↓
implementation or reasoning