Skip to content

AI_CONTEXT.md

Latest commit

 

History

History
206 lines (185 loc) · 8.84 KB

AI_CONTEXT.md

File metadata and controls

206 lines (185 loc) · 8.84 KB
Raw

AI Context

This file is the compact project summary for agents working in this repository.

Project

  • Name: Pragmatik.
  • Purpose: reusable documentation, workflow, preset, and template library for AI-assisted software projects.
  • Current version: 0.3.3.
  • Primary audience: Mauricio Vuljevas projects and future reusable project foundations.

Stack

  • Runtime: Node.js CLI plus documentation and templates.
  • Frameworks: none.
  • Package manager: npm.
  • Version source: VERSION.
  • Release tags: vX.Y.Z.

Repository Shape

.
├── AGENTS.md
├── README.md
├── VERSION
├── package.json
├── cli/
│   └── pragmatik.js
├── docs/
│   ├── PRAGMATIK_CLI.md
│   ├── AI_CONTEXT.md
│   ├── AI_CLIENTS.md
│   ├── AI_SEARCH.md
│   ├── AI_MEASUREMENT.md
│   ├── AI_TOOL_SETUP.md
│   ├── AI_TOOL_REGISTRY.md
│   ├── AI_USAGE_REPORT.md
│   ├── AI_OPTIMIZATION_REPORT.md
│   ├── AI_TOKEN_BUDGET.md
│   ├── CATALOG.md
│   ├── CONVENTIONS.md
│   ├── INSTALLATION.md
│   ├── NAMING.md
│   ├── ROADMAP.md
│   ├── SNAPSHOTS.md
│   ├── TECHDEBT.md
│   └── WORKFLOWS.md
├── presets/
│   └── lean-context/
├── .githooks/
│   └── pre-commit
├── scripts/
│   └── ai-tools.sh
└── templates/
    ├── chrome-extension-vanilla/
    ├── docs-only/
    ├── laravel-react/
    └── react-vite-spa/

Key Commands

# inspect state
git status --short --branch

# CLI
node cli/pragmatik.js doctor
node cli/pragmatik.js setup --dry-run
node cli/pragmatik.js dashboard --no-open

# search
rg "pattern"
rg --files

# validate JSON preset files
python3 -m json.tool presets/lean-context/files/repomix.config.json >/dev/null
python3 -m json.tool presets/lean-context/files/github/labels.json >/dev/null

# validate whitespace
git diff --check

Important Files

  • README.md: repository purpose, shared standards, and preset catalog.
  • AGENTS.md: active agent workflow rules for this repository.
  • VERSION: authoritative version source for this repository.
  • package.json: npm package metadata for @mvuljevas/pragmatik.
  • cli/pragmatik.js: project CLI with pragmatik help, setup, doctor, dashboard, suggest, run, and MCP scaffold commands.
  • docs/PRAGMATIK_CLI.md: public CLI usage guide.
  • docs/AI_TOOL_REGISTRY.md: optional tool registry and adapter contract.
  • docs/CATALOG.md: source of truth for available and planned templates and presets.
  • docs/INSTALLATION.md: local package testing and future distribution channels.
  • docs/ROADMAP.md: primary source for next-step suggestions.
  • docs/SNAPSHOTS.md: chronological project memory.
  • docs/TECHDEBT.md: fallback source for next-step suggestions and debt automation.
  • docs/AI_TOOL_SETUP.md: local setup guide for optional Context7, Tokscale, Repomix, Tokscale dashboard, and MCP optimization tooling.
  • docs/AI_CLIENTS.md: client-specific setup matrix for Codex, Cursor, Claude, Gemini, Antigravity, Warp, OpenCode, and local-model workflows.
  • docs/AI_MEASUREMENT.md: baseline vs lean-context measurement workflow.
  • docs/AI_USAGE_REPORT.md: aggregate usage observations for this repository.
  • docs/AI_OPTIMIZATION_REPORT.md: aggregate optimization observations for measured usage, bounded context size, and client coverage.
  • scripts/ai-tools.sh: local automation for Context7, Tokscale, Repomix, and aggregate usage and optimization reporting based on .agents.env.
  • .githooks/pre-commit: optional commit-time automation for active AI tools when AGENTS_AUTO_RUN_ON_COMMIT=on.
  • .agents/skills/context7-mcp/SKILL.md: project-local Context7 usage skill generated by Context7 setup.
  • docs/CONVENTIONS.md: template and preset conventions.
  • docs/WORKFLOWS.md: shared workflow rules.
  • presets/lean-context/: reusable preset for lean context loading.
  • templates/: available project templates.
  • presets/lean-context/docs/RECOMMENDATION_FLOW.md: guide for recommending a template and preset combination before adoption.
  • Root and preset AI docs: optional MCP, usage-tracking, client setup, and token-reduction guidance.

Current Decisions

  • Root documentation is written in concise English.
  • Spanish phrases appear only as prompt examples that agents should recognize.
  • Project templates will live under templates/<project-type>/.
  • Reusable workflow layers live under presets/<preset-name>/.
  • lean-context is both stored as a preset and applied to this repository.
  • Agents should recommend templates and presets before copying or applying them.
  • Agents must check docs/CATALOG.md before claiming a template can be copied.
  • Templates recommend MCPs and tracking tools, but agents must ask before writing secrets or changing machine-wide integrations.
  • Local Context7 is configured for this repository through ignored project configuration; examples are versioned without secrets.
  • Analysis prompts trigger an optional AI tool check before implementation work.
  • Templates include Codex, Cursor, Warp, generic MCP, Context7, Tokscale, and Repomix setup examples while keeping real config files ignored.
  • Templates include .agents.env and .ai-usage-log.example.md for comparable baseline vs lean-context runs.
  • This repository has local ignored measurement files active and an initial aggregate usage report.
  • Active tools can be automated with bash scripts/ai-tools.sh run.
  • Matched baseline-vs-lean-context comparisons can be automated with bash scripts/ai-tools.sh measure-pair; the command appends a comparison table to docs/AI_USAGE_REPORT.md.
  • Root, preset, and templates now include the same AI tool automation script.
  • Commit-time automation is available through bash scripts/ai-tools.sh install-hooks and .githooks/pre-commit.
  • Tokscale remote dashboard submission is available through AGENTS_TOKSCALE_SUBMIT=on|dry-run|off; templates default to dry-run.
  • Tokscale coverage is client-dependent and must be checked with npx -y tokscale@latest clients when users switch agents or IDEs.
  • Tokscale is authenticated locally for this repository and a successful Codex submission was recorded for 2026-06-29.
  • Tokscale automation supports multi-client measurement through AGENTS_TOKSCALE_CLIENTS and optional Cursor, Antigravity, and Warp sync commands.
  • Template .agents.env files keep external tools optional while enabling dashboard-ready local reporting defaults.
  • A blind non-Codex coverage probe showed that unsupported local agents can run successfully while Tokscale records only supported local client data.
  • Tokscale is treated as observability only; Repomix compression and MCP optimization layers are treated as optional token-reduction tools.
  • At iteration close, agents must suggest the next step from roadmap first, technical debt second, and user preference third.
  • Pushes remain explicit; local commits and tags may be created during closed versioned iterations.
  • pragmatik is the public CLI command.
  • The CLI is the preferred setup and dashboard path. pragmatik run falls back to the backend bundled in the npm package when a project-local scripts/ai-tools.sh override is absent.
  • Existing repositories should receive additive scripts such as pragmatik:dev, not automatic replacement of normal dev scripts.
  • Pragmatik must not depend on any third-party service for its core measurement and reporting functions. Token estimation reads local AI client transcripts. Cost estimation uses a built-in model pricing table. Human-vs-AI comparison is computed locally. External tools (Tokscale, Repomix, Context7) are optional plugins, not required dependencies.
  • scripts/ai-tools.sh is frozen at v0.3.x and will be deprecated in v1.0.0. All new measurement and reporting logic is built in Node.js.
  • PRAGMATIK_HOURLY_RATE and PRAGMATIK_MODEL_PRICE_INPUT/OUTPUT in .agents.env control the human-vs-AI cost comparison.
  • Submit is opt-in (PRAGMATIK_SUBMIT=on). Only non-personal aggregate metrics are ever sent. Content, paths, and identifiers are never included.

Current Risks

  • pragmatik mcp-create creates an initial read-only MCP scaffold, but it is not a full MCP runtime implementation yet.
  • lean-context has not yet proven token savings with real measurements.
  • Third-party MCP, tracking, and compression tools can change quickly and should be rechecked before automation is added.
  • The autonomous measurement layer (pragmatik measure) does not yet exist. Until v0.4.0, token measurement still requires Tokscale or manual input.
  • Version 0.3.2 was skipped. See TD-009 in docs/TECHDEBT.md.

Search Notes

  • Use docs/AI_SEARCH.md before opening broad directories.
  • Prefer slices over full files.
  • Do not inspect ignored or generated paths unless directly needed.