slaid098/opencode-config
1
0
Fork 0
Code Issues 3 Pull requests Projects Releases Packages Wiki Activity Actions
opencode-config/docs/project-map/README.md
Sergey f06d36140b
feat(pipeline): add check_project_map to DOCS phase (#67) 
* feat(pipeline): add check_project_map to DOCS phase

* test(pipeline): add check_project_map unit tests + update check_docs tests

* docs(adr): add ADR-028 project map contract

* docs(project-map): mention check_project_map guard in Update Protocol

* docs(handoff): add PR handoff for check_project_map

* docs(handoff): set PR number 67

* docs(review): fix PR#66 to PR#67 typo in project map and handoff

* fix(ci): ruff lint errors in pipeline-status and project map test

---------

Co-authored-by: opencode-agent <agent@opencode.local>
2026-07-26 00:07:13 +03:00

12 KiB
Raw Blame History

Project Map

opencode-config — Docker-based AI coding assistant with persistent memory (opencode configuration). Runs in Docker via docker-compose.yml (dind + opencode services).

Root AGENTS.md — orchestrator directive (chat = plan only, all via subagents) + global rules (pipeline, code style, language RU) + ## Tool Usage Policy (таблица 10 tools: commit/create_pr/create_issue/merge_pr/post_review/post_docs_review/pipeline_status/spec_status/memory_setup/tunnel; raw bash заблокирован deny, при сбое tool — STOP, НЕ fallback). Auto-loaded for project + bind-mounted globally in container — PR#31, PR#63.

Structure

opencode-config/
├── .github/
│   ├── workflows/
│   │   ├── ci.yml                  # Lint, test, typecheck, complexity (bootstrap + output-based skip)
│   │   ├── permissions-check.yml  # .opencode/scripts/check-permissions.py validator (step-level skip)
│   │   └── adr-check.yml           # ADR cross-reference validator (.opencode/scripts/check-adr-refs.py)
│   └── dependabot.yml              # pip + github-actions ecosystem updates
├── .opencode/                      # Project-local opencode config (auto-discovery, zero env var) — PR#23
│   ├── agents/
│   │   ├── docs-reviewer.md        # Docs validation subagent (project map + handoff + ADR, uses `commit`+`post_docs_review` tools) — PR#40, PR#46
│   │   ├── memory-syncer.md        # Distills gotchas from handoffs into opencode-memory
│   │   └── reviewer.md             # Code review subagent (verdict via `post_review` tool: APPROVE|REQUEST_CHANGES|NEEDS_DISCUSSION) — PR#46
│   ├── commands/
│   │   ├── configure-opencode.md   # /configure-opencode — edit opencode.json
│   │   ├── run-pipeline.md          # /run-pipeline — 7-phase PR pipeline
│   │   └── spec.md                  # /spec — 9-phase spec generation
│   ├── skills/
│   │   ├── add-skill/SKILL.md      # Create new opencode skill
│   │   ├── branch/SKILL.md         # Branch naming conventions
│   │   ├── code-standards/SKILL.md # Universal code style rules
│   │   ├── configure-opencode/SKILL.md # Canonical rule: write to .opencode/
│   │   ├── get-project-map/SKILL.md # Maintain docs/project-map/
│   │   ├── issue/SKILL.md          # GitHub issue creation
│   │   ├── memory/SKILL.md         # opencode-memory usage guide
│   │   ├── run-pipeline/SKILL.md # 7-phase pipeline orchestration
│   │   ├── python-development/SKILL.md # Python dev patterns
│   │   ├── release/SKILL.md        # Tag + GitHub Release
│   │   ├── repo-init/SKILL.md      # New repository bootstrap
│   │   ├── tunnel/SKILL.md         # Cloudflare tunnel toggle (tool `tunnel()`: 1-й вызов start, 2-й stop) — PR#63 (восстановлен, удалён в PR#42)
│   │   ├── run-tests/SKILL.md      # Test runner guide
│   │   └── spec/SKILL.md           # 9-phase spec generation
│   ├── tools/
│   │   ├── _shared.ts              # Shared module for GitHub tools: parseRepo(repo?), runGh(args, repo?, opts?), formatResult(r, toolName) — PR#65
│   │   ├── commit.ts               # commit tool wrapper (1 arg message, validates format+staged) — PR#38
│   │   ├── create-issue.ts         # create-issue tool wrapper (3 args, validates format+labels; optional repo?: string) — PR#38, PR#65
│   │   ├── create-pr.ts            # create-pr tool wrapper (3 args, validates format+Closes #N; optional repo?: string) — PR#38, PR#65
│   │   ├── merge-pr.ts            # merge_pr tool wrapper (orchestrator-safe gh pr merge; optional repo?: string) — PR#30, PR#65
│   │   ├── memory-setup.ts         # memory_setup tool wrapper (0 args, calls setup-memory.sh) — PR#36
│   │   ├── pipeline-status.ts      # pipeline_status tool wrapper
│   │   ├── post-docs-review.ts     # post_docs_review tool wrapper (3 args: pr_number, verdict enum, body; deterministic ## Docs Review Summary heading; optional repo?: string) — PR#46, PR#65
│   │   ├── post-review.ts          # post_review tool wrapper (3 args: pr_number, verdict enum, body; deterministic ## Code Review Summary heading; optional repo?: string) — PR#46, PR#65
│   │   ├── spec-status.ts          # spec_status tool wrapper
│   │   └── tunnel.ts               # Cloudflare tunnel toggle tool (start/stop без args) — PR#34
│   ├── scripts/
│   │   ├── check-adr-refs.py       # ADR cross-reference validator (adr-check.yml)
│   │   ├── check-permissions.py    # Permissions validator (permissions-check.yml)
│   │   ├── observability.py        # OTel spans for tools
│   │   ├── pipeline-status.py      # 7-phase oracle (gh PR + CI polling, NEXT_ACTIONS with subagent_type+template) — PR#42, PR#67 (check_project_map guard)
│   │   ├── scaffold-handoff.sh     # Scaffold handoff + ADR stubs
│   │   ├── setup-memory.sh         # opencode-memory bootstrap (deterministic 6-step flow, idempotent) — PR#36
│   │   ├── spec-status.py          # 9-phase spec oracle
│   │   └── tunnel.sh               # Cloudflare tunnel toggle bash (named mode via CLOUDFLARE_TUNNEL_TOKEN) — PR#34
│   ├── opencode.json               # MCP servers, providers, permissions, agents (role-based tools), plugins — PR#40
│   ├── package.json                # npm deps for tools/*.ts
│   └── .gitignore                  # Ignores node_modules, etc.
├── docs/
│   ├── handoff/                   # PR handoffs (pr-<N>-<slug>.md)
│   ├── decisions/                 # ADRs (NNN-pr-<N>-<slug>.md)
│   └── project-map/               # This file — structure snapshot
├── src/                           # Python RAG CLI (second-brain) — PR#17
│   └── memory/
│       ├── __init__.py
│       ├── __main__.py            # Entry point for `python -m memory`
│       ├── cli.py                 # CLI commands
│       ├── embedder.py            # Embedding via AI_PROVIDER_API_URL (env-only)
│       ├── index.py               # Indexing
│       └── search.py              # Search
├── tests/                         # pytest + TS/MJS test suite — PR#17
│   ├── _ts_loader.mjs             # TS test loader (load/exec_stub/exec_stub_json/exec_real modes; relative import inlining via inlineShared()) — PR#38, PR#65
│   ├── test_agent_frontmatter.py  # Agent frontmatter validators (no top-level doom_loop, permission.doom_loop present, steps:100) — PR#49
│   ├── test_check_adr_refs.py     # adr-check.yml validator
│   ├── test_check_permissions.py  # permissions-check.yml validator
│   ├── test_cli.py                # src/memory/cli.py
│   ├── test_docker_compose.py    # docker-compose.yml port exposure (0.0.0.0:4096, no 127.0.0.1) — PR#51
│   ├── test_dockerfile.py        # Dockerfile npm install (opencode-ai + repomix + @mathew-cf/opencode-memory) — PR#57
│   ├── test_commit_tool.py        # .opencode/tools/commit.ts (via _ts_loader.mjs exec_stub_json) — PR#38
│   ├── test_commit_tool.ts        # TS wrapper test (mjs loader) — PR#38
│   ├── test_create_issue_tool.py  # .opencode/tools/create-issue.ts (via _ts_loader.mjs exec_stub_json; +repo explicit/omitted/invalid) — PR#38, PR#65
│   ├── test_create_issue_tool.ts  # TS wrapper test (mjs loader; +repo cases) — PR#38, PR#65
│   ├── test_create_pr_tool.py     # .opencode/tools/create-pr.ts (via _ts_loader.mjs exec_stub_json; +repo explicit/omitted/invalid) — PR#38, PR#65
│   ├── test_create_pr_tool.ts     # TS wrapper test (mjs loader; +repo cases) — PR#38, PR#65
│   ├── test_embedder.py           # src/memory/embedder.py (mocks AI_PROVIDER_API_URL)
│   ├── test_index.py              # src/memory/index.py
│   ├── test_memory_setup_tool.py  # .opencode/tools/memory-setup.ts (via _ts_loader.mjs) — PR#36
│   ├── test_memory_setup_tool.ts  # TS wrapper test (mjs loader) — PR#36
│   ├── test_merge_pr_tool.py      # .opencode/tools/merge-pr.ts (via _ts_loader.mjs; 8 tests: base + repo explicit/omitted/invalid) — PR#65
│   ├── test_merge_pr_tool.ts      # TS wrapper test (mjs loader; 5 tests: base + repo) — PR#65
│   ├── test_observability.py      # .opencode/scripts/observability.py
│   ├── test_permissions.py        # Global deny rules + agent.<name>.tools role-based access (8 tests) — PR#40
│   ├── test_pipeline_status.py    # .opencode/scripts/pipeline-status.py (REVIEW verdict branching)
│   ├── test_pipeline_status_adr.py
│   ├── test_pipeline_status_ci.py
│   ├── test_pipeline_status_next_actions.py # NEXT_ACTIONS subagent_type+template per phase (25 tests) — PR#42
│   ├── test_pipeline_status_project_map.py  # check_project_map guard (README.md mandatory, ADR-028) — PR#67
│   ├── test_pipeline_status_tool.py
│   ├── test_pipeline_status_tool.ts  # TS wrapper test (mjs loader)
│   ├── test_post_docs_review_tool.py # .opencode/tools/post-docs-review.ts (via _ts_loader.mjs exec_stub_json; +repo cases) — PR#46, PR#65
│   ├── test_post_docs_review_tool.ts # TS wrapper test (mjs loader; +repo cases) — PR#46, PR#65
│   ├── test_post_review_tool.py    # .opencode/tools/post-review.ts (via _ts_loader.mjs exec_stub_json; +repo cases) — PR#46, PR#65
│   ├── test_post_review_tool.ts    # TS wrapper test (mjs loader; +repo cases) — PR#46, PR#65
│   ├── test_search.py             # src/memory/search.py
│   ├── test_setup_memory.py       # .opencode/scripts/setup-memory.sh (mock remote, idempotency) — PR#36
│   ├── test_spec_status.py        # .opencode/scripts/spec-status.py
│   ├── test_spec_status_tool.py
│   ├── test_tunnel_tool.py        # .opencode/scripts/tunnel.sh (6 pytest: start/stop/stale PID/toggle, isolated tmp copy + fake cloudflared) — PR#65
│   └── test_tunnel_tool.ts        # .opencode/tools/tunnel.ts (4 TS: spawnSync wiring, success/error/cwd) — PR#65
├── pyproject.toml                 # Python project (uv, ruff, pytest config)
├── uv.lock                        # Locked deps for Python project
├── .pre-commit-config.yaml        # ruff + UV hooks
├── docker-compose.yml             # 2 services (dind + opencode), opencode_network, 4 bind mounts, port 4096 on 0.0.0.0 — PR#24, PR#51
├── Dockerfile                     # node:20-slim + uv + gh + chromium + docker.io + opencode-ai + repomix + @mathew-cf/opencode-memory + cloudflared — PR#24, PR#34, PR#57
├── .env.example                   # Placeholder-only env template (user copies to .env) — PR#24, PR#34 (TUNNEL_DOMAIN), PR#36 (OPENCODE_MEMORY_REMOTE/DIR)
├── app_data/
│   ├── opencode-memory/           # Persistent memory (separate git repo, gitignored) — PR#36
│   ├── workspaces/                # Agent working directory (.gitkeep)
│   └── ssh/                       # SSH keys, not in git (.gitkeep)
├── .editorconfig
├── .gitignore
├── .python-version
├── AGENTS.md                       # Orchestrator directive + global rules (bind-mounted globally) — PR#31
├── LICENSE
└── README.md

Pending (future PRs)

  • .opencode/scripts/pipeline-status.py fix 610452f — PR#7 (config/scripts/ migration)
  • .opencode/tools/ TS wrappers — PR#7 (config/tools/ migration)

Update Protocol

Updated by docs-reviewer subagent on each PR. Reflects tracked files only (git ls-files).

Guarded by pipeline-status.py:check_project_map — README.md existence is mandatory.