Imported from october-academy/agentic30 (AGENTS.md). Install upstream with npx skills add october-academy/agentic30. Copyright stays with the author.

PROJECT KNOWLEDGE BASE: agentic30-public

OVERVIEW

Native macOS menu bar assistant with a SwiftUI/AppKit shell and a local Node.js ESM sidecar. The app owns macOS surfaces, Keychain/OAuth, telemetry preferences, and the WebSocket client; the sidecar owns provider execution, MCP/ACP, workspace scanning, curriculum state, foundation-summary review, BIP, and external integrations.

STRUCTURE

agentic30-public/
├── agentic30/              # Swift app target; not SwiftPM
├── agentic30.xcodeproj/    # Xcode project; edit deliberately, not by hand casually
├── agentic30Tests/         # Swift XCTest unit coverage
├── agentic30UITests/       # Blocking desktop XCUITest coverage
├── sidecar/                # Node ESM daemon, MCP/ACP, provider runners
├── sidecar-tests/          # node:test integration suite
├── sidecar-evals/          # dogfood evaluator and fixtures
├── scripts/                # build, release, sync, preflight, test wrappers
├── ci_scripts/             # Xcode Cloud post-clone/pre-xcodebuild hooks
├── docs/                   # product, specs, diagnostics, release docs
├── mockups/                # static IA/design HTML prototypes; not app source
└── .github/                # workflows, PR template, issue templates

WHERE TO LOOK

CODE MAP

CONVENTIONS

• Swift uses an Xcode project layout, not SwiftPM. Add files to the proper target membership when needed.
• Node code is ESM (.mjs) with explicit named exports; package.json is the command registry.
• There is no repo-level ESLint, Prettier, EditorConfig, SwiftLint, or SwiftFormat config. Follow local style and tests.
• Sidecar stateful subsystems persist versioned JSON under the selected workspace's .agentic30/; schema bumps require migration coverage.
• Release distribution is Developer ID signed/notarized PKG first, DMG fallback, plus Sparkle appcast. Mac App Store and App Sandbox are intentionally out of scope.
• CLAUDE.md mirrors cross-cutting guidance for Claude Code; closest AGENTS.md remains the directory-scoped source for agents.

ANTI-PATTERNS

• Do not edit sidecar/vendor/ directly. It is synced from upstream by scripts/sync-gstack.mjs.
• Do not run local UI E2E without explicit approval. Ask: "이 명령은 Agentic30 앱을 전면으로 띄우고 키보드/마우스/포커스를 점유할 수 있습니다. 지금 실행할까요?" Then set AGENTIC30_ALLOW_BLOCKING_UI_E2E=1.
• Do not introduce time-of-day, locale, network, or live-provider assumptions into default tests.
• Do not log raw API keys, OAuth tokens, Keychain values, or workspace secrets.
• Do not hand-roll inline-decision parsing; use the sentinel helpers in sidecar/inline-decision.mjs.

COMMANDS

npm install
npm run doctor
npm run check:public-safety
npm run test:sidecar
npm run test:swift:unit
npm run build:sidecar
npm run preflight:bundle
npm run eval:dogfood
npm run eval:dogfood:gate
AGENTIC30_ALLOW_BLOCKING_UI_E2E=1 npm run test:swift:ui:smoke
AGENTIC30_ALLOW_BLOCKING_UI_E2E=1 npm run test:swift:ui:full

NOTES

• Build, cache, local state, and artifact directories can exist in the checkout (build/, sidecar-build/, sidecar-evals/.artifacts/, .agentic30/, .omo/, .omc/, .omx/, Library/, _workspace/). Do not score or document them as source modules.
• Local tool/config folders such as .agents/, .claude/, .codex/, .gstack/, .codegraph/, and root scratch reports are not app/sidecar modules unless tracked and explicitly wired.
• Bridge-contract edits need both Swift and sidecar tests: npm run test:sidecar and npm run test:swift:unit.
• Live provider canaries are opt-in behind AGENTIC30_RUN_LIVE_PROVIDER_*=1 and related credential env vars.
• Public-safety and secret scans are part of the normal contribution surface: npm run check:public-safety, optional npm run scan:secrets:gh.

USER CONTEXT

• User-designated competitors to remember for future strategy/product/market work:
  • https://indiefounders.net/
  • https://www.threads.com/@classbinu
  • https://tekk.coach/
  • https://pre.dev/
  • https://www.ventureos.com/
  • https://www.cofounderos.ai/
• Coding preference: prefer explicit failure that exposes the root cause over meaningless fallback or recovery logic.