@inventeer.tech/apex 0.2.31 → 0.2.33

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +376 -18
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,53 +1,411 @@
1
1
  # @inventeer.tech/apex
2
2
 
3
- **AI-powered software delivery agent. From task to merged PR across multiple repos.**
3
+ **AI-powered software delivery agent. From task description to open pull request — across multiple repos.**
4
4
 
5
- This is the npm wrapper for the [APEX CLI](https://github.com/Inventeer/apex). It downloads the correct pre-built binary for your platform on install.
5
+ [![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey?style=flat)]()
6
+ [![License MIT](https://img.shields.io/badge/license-MIT-blue?style=flat)](https://github.com/Inventeer/apex/blob/main/LICENSE)
7
+ [![npm](https://img.shields.io/npm/v/@inventeer.tech/apex?style=flat)](https://www.npmjs.com/package/@inventeer.tech/apex)
8
+
9
+ ---
10
+
11
+ ## What is APEX?
12
+
13
+ APEX is a terminal CLI that takes a developer from a Linear ticket to open pull requests across all their repositories — with full codebase awareness, persistent memory, and zero configuration files left in repos.
14
+
15
+ You describe the task, approve the plan, and watch the changes land in real time across every repository in your stack.
16
+
17
+ **What runs on your machine:** the `apex` binary, a native AI runtime engine, and your git repos.
18
+ **What lives in the cloud:** codebase semantic search (RAG), episodic session memory, LLM proxy, org config.
19
+ **What never happens:** files created in your repos.
20
+
21
+ ---
6
22
 
7
23
  ## Install
8
24
 
9
25
  ```bash
26
+ # npm (cross-platform)
10
27
  npm install -g @inventeer.tech/apex
28
+
29
+ # macOS — Homebrew
30
+ brew install Inventeer/tap/apex
11
31
  ```
12
32
 
13
- Supports macOS (x64/arm64), Linux (x64/arm64), and Windows (x64).
33
+ The binary is self-contained — no Go, Docker, or external runtime required.
34
+
35
+ ```bash
36
+ apex version # verify install
37
+ apex doctor # run pre-flight checks
38
+ ```
39
+
40
+ ---
41
+
42
+ ## Why APEX is Different
43
+
44
+ | | Terminal AI assistant | Autonomous cloud agent | **APEX** |
45
+ |---|---|---|---|
46
+ | **Scope** | One file at a time | One task, one repo | One task, **all repos** |
47
+ | **Execution** | Local, inline edits | Remote sandbox — you wait | Local — you watch changes live |
48
+ | **Plan approval** | No | No | **Yes — nothing runs without your sign-off** |
49
+ | **Memory between sessions** | None | Limited | **Episodic memory — resumes in <500 tokens** |
50
+ | **Codebase context** | Open files only | Repo snapshot | **Full RAG across all repos, always fresh** |
51
+ | **Org knowledge** | None | None | **ADRs, runbooks, specs — permanently searchable** |
52
+ | **Architectural decisions** | None | None | **Logged automatically, queryable** |
53
+ | **Delivery workflow** | Chat | Autonomous | **Phased: investigate → plan → implement → validate → ship** |
54
+ | **Quality gate** | Manual | Basic CI | **Pre-PR: tests + lint + type check + auto-fix** |
55
+ | **Token visibility** | None | None | **Per-model usage tracking** |
56
+
57
+ ### An invisible senior engineer on every task
58
+
59
+ Every time you run a command in APEX, a curated framework of specialized agents, skills, and guardrails activates silently in the background — loaded from the cloud at startup, invisible to you, updating without any action on your part.
60
+
61
+ **8 specialized agents** swap in automatically depending on what you're doing:
62
+
63
+ - `/eng.start` activates the delivery agent — investigates, recalls past sessions, maps cross-repo dependencies
64
+ - `/eng.pre-pr` activates the code reviewer + QA test planner in parallel
65
+ - `/eng.debug` activates the bug hunter — root-cause analysis, not guessing
66
+ - `/qa-gate` activates the quality champion with numeric scoring
67
+
68
+ **30+ operational skills** activate on demand, invisibly:
69
+
70
+ - Detected sequential DB writes? The `eng-database` skill activates — transaction boundaries, rollback scenarios, isolation levels
71
+ - Found `.graphql` files in scope? The `eng-graphql` skill activates — schema validation, codegen, type contracts
72
+ - Pre-PR check? `qa-static-analysis`, `qa-security-scan`, `qa-test-plan`, and `eng-confidence` run in sequence
73
+ - Opening PRs? `eng-pr` and `eng-github` ensure branch naming, commit conventions, and cross-repo dependency notes
74
+
75
+ **Phase guardrails enforced by rules, not discipline:**
76
+
77
+ - `/eng.start` — no code written, analysis only
78
+ - `/eng.plan` — no code, no commits, plan only
79
+ - `/eng.work` — no commits until `/eng.pr`
80
+ - Acceptance criteria must exist before investigation proceeds
81
+ - Breaking changes require documented consumer impact
82
+
83
+ None of this requires configuration. It's part of every session, for every developer in your organization.
84
+
85
+ ---
86
+
87
+ ### Multi-repo by design
88
+
89
+ A workspace groups all your repositories. One task can plan, write, test, and open PRs across your backend, frontend, and shared types simultaneously. The AI knows your full stack — not just the file you have open.
90
+
91
+ ### Five layers of always-active context
92
+
93
+ Every LLM call carries five layers injected automatically — you never paste context manually:
94
+
95
+ - **Codebase RAG** — every file across all repos, chunked and semantically indexed. The AI knows your schema when writing the endpoint, and your types when writing the frontend.
96
+ - **Episodic memory** — when you close the terminal, APEX saves a structured summary (completed, pending, files changed, decisions made, next steps). The next session resumes in under 500 tokens. After months of work, APEX still knows why things were built the way they were.
97
+ - **Org knowledge base** — ADRs, runbooks, API specs, onboarding docs uploaded with `apex knowledge add` are permanently searchable. The AI cites your actual documentation instead of inventing conventions.
98
+ - **Working context** — the full active session state, preserved mid-task.
99
+ - **Framework intelligence** — curated engineering agents, quality guardrails, and delivery workflows loaded at startup. No configuration required.
100
+
101
+ ### Plan before code — you stay in control
102
+
103
+ APEX never writes a line of code without showing you a phased plan first. You approve, edit, or cancel before any file is touched. Every run of `/eng.work` is a deliberate, reviewed commitment.
104
+
105
+ ### Built-in quality gates
106
+
107
+ `/eng.pre-pr` runs tests, type checks, and lint across all repos before any PR is opened. Failures are auto-fixed up to 3 times. You see a scored quality report before anything goes to review.
108
+
109
+ ### Self-correcting execution loop
110
+
111
+ The AI doesn't stop on the first test failure. It diagnoses the error, tries a different strategy, and escalates through recovery hints before surfacing a report. Sessions run until real progress stops — not until a fixed step count is hit.
112
+
113
+ ### Architectural decisions, not just code
114
+
115
+ Every decision the AI makes — why it chose an approach, what it considered — is recorded automatically and stored. Run `apex decisions` to see the full log. New team members can understand why the code was written the way it was.
116
+
117
+ ### Always-fresh codebase context
14
118
 
15
- ## Usage
119
+ Push webhooks trigger incremental re-indexing automatically on every commit. The TUI shows an amber warning when the index is stale. The AI is never working from outdated code.
120
+
121
+ ### Token visibility, per model
122
+
123
+ Every LLM call is metered. Run `apex usage` to see token consumption broken down by model and provider. No surprise bills, no silent runaway sessions.
124
+
125
+ ---
126
+
127
+ ## The Workspace Concept
128
+
129
+ > This is the most important thing to understand about APEX.
130
+
131
+ A **workspace** is a named group of repositories that APEX treats as a single unit. When you start a task, APEX reads, understands, and writes code across **all repos in the workspace simultaneously** — like a senior engineer who has the full stack loaded in their head.
132
+
133
+ ```
134
+ workspace: payment-platform
135
+ ├── backend/ (Node.js API)
136
+ ├── frontend/ (React app)
137
+ └── shared-types/ (TypeScript contracts)
138
+ ```
139
+
140
+ When APEX works on `ENG-123: add refund endpoint`, it:
141
+ - Reads the backend schema, frontend payment hooks, and shared type definitions
142
+ - Generates a plan that touches all three repos
143
+ - Writes changes across all repos in one session
144
+ - Opens one PR per repo, with cross-repo dependency notes in each body
145
+
146
+ **You register each repo once**, then forget about it:
16
147
 
17
148
  ```bash
18
- # Authenticate (once per machine)
149
+ cd ~/repos/backend && apex init
150
+ cd ~/repos/frontend && apex init
151
+ cd ~/repos/shared-types && apex init
152
+ ```
153
+
154
+ APEX detects the git remote and technology stack automatically. All three repos are now in the same workspace.
155
+
156
+ ---
157
+
158
+ ## Setup (once per machine)
159
+
160
+ ### 1 — Install and authenticate
161
+
162
+ ```bash
163
+ npm install -g @inventeer.tech/apex
19
164
  apex login
165
+ ```
166
+
167
+ `apex login` opens the GitHub Device Flow in your browser. After approval, your organization's AI configuration — models, credentials, and behavior — is loaded automatically from the cloud.
168
+
169
+ ### 2 — Connect Linear
170
+
171
+ ```bash
172
+ apex auth linear
173
+ ```
174
+
175
+ This opens the Linear OAuth flow. Once connected, APEX fetches full ticket details, acceptance criteria, and linked issues every time you start a task with a Linear ID.
176
+
177
+ ### 3 — Register your repos
178
+
179
+ Run from inside each repository you want APEX to work with:
20
180
 
21
- # Register your repo
22
- cd ~/repos/backend && apex init
181
+ ```bash
182
+ cd ~/repos/backend && apex init
183
+ cd ~/repos/frontend && apex init
184
+ ```
185
+
186
+ APEX auto-detects the git remote and groups repos into a workspace.
23
187
 
24
- # Index for RAG
188
+ ### 4 — Index the codebase
189
+
190
+ ```bash
25
191
  apex index
192
+ ```
193
+
194
+ Reads all source files, chunks them into overlapping segments, generates semantic embeddings, and stores them for search. Run once after registration, and again after large changes.
195
+
196
+ > The TUI shows an amber warning when the RAG index is more than 24 hours old.
197
+
198
+ ### 5 — Launch
26
199
 
27
- # Launch
200
+ ```bash
28
201
  apex
29
202
  ```
30
203
 
31
- ## What is APEX?
204
+ APEX opens the workspace selector and the 3-panel TUI. From here, everything happens through slash commands.
205
+
206
+ ```
207
+ ╔═══════════════════════════════════════════════════════════════════════════╗
208
+ ║ APEX ▸ payment-platform v0.2.32 ║
209
+ ╠══════════════════╦════════════════════════════════╦════════════════════════╣
210
+ ║ Workspace ║ ║ Live Diff ║
211
+ ║ ────────────── ║ APEX ║ ──────────────────── ║
212
+ ║ • backend ║ Workspace ready: ║ backend/ ║
213
+ ║ • frontend ║ › 2 repos indexed ║ src/payments/ ║
214
+ ║ • shared-types ║ › 4,139 files in RAG ║ client.ts +12 -3 ║
215
+ ║ ║ › Episodic memory: 7 sessions║ ║
216
+ ║ Sessions ║ ║ frontend/ ║
217
+ ║ ─────────────── ║ Type /init-apex to begin ║ src/checkout/ ║
218
+ ║ 1 paused ║ or /warm-up to load context ║ Payment.tsx +8 -1 ║
219
+ ╠══════════════════╩════════════════════════════════╩════════════════════════╣
220
+ ║ › _ ║
221
+ ╚═══════════════════════════════════════════════════════════════════════════╝
222
+ ```
223
+
224
+ ---
225
+
226
+ ## The Delivery Workflow
227
+
228
+ Every engineering task follows this sequence inside the TUI.
229
+
230
+ ---
231
+
232
+ ### `/init-apex` · Initialize (first use)
233
+
234
+ ```
235
+ /init-apex
236
+ ```
237
+
238
+ Run once when starting in a new workspace. APEX loads your organization's configuration, reads environment files across repos, and bootstraps the session context.
239
+
240
+ ---
241
+
242
+ ### `/warm-up` · Load context (start of each day)
243
+
244
+ ```
245
+ /warm-up
246
+ ```
32
247
 
33
- APEX takes a developer from a task description to open pull requests across multiple repositories with full context awareness, episodic memory, and zero configuration files left in your repos.
248
+ APEX reads git status across all repos, loads recent architectural decisions, recalls past sessions, and builds a fresh summary of where things stand. Run this each morning or at the start of a new session. Takes ~30 seconds.
249
+
250
+ ---
251
+
252
+ ### `/eng.start ENG-XX` · Investigate
253
+
254
+ ```
255
+ /eng.start ENG-123
256
+ ```
257
+
258
+ APEX fetches the Linear ticket (description, acceptance criteria, linked issues), recalls relevant past sessions from episodic memory, and searches the codebase via semantic RAG. It produces a full cross-repo investigation report with a clear problem statement and scope.
259
+
260
+ ---
261
+
262
+ ### `/eng.plan` · Build the execution plan
34
263
 
35
264
  ```
36
- apex /eng.start TASK-456
265
+ /eng.plan
37
266
  ```
38
267
 
39
- The AI fetches the ticket, investigates all workspace repos, proposes a cross-repo plan, and executes it step by step. When you close the terminal, the session is summarized. Next time, APEX resumes in under 500 tokens of overhead.
268
+ Based on the investigation, APEX generates a phased cross-repo implementation plan broken into atomic tasks, one per file or concern, across all affected repos. Review the plan carefully.
269
+
270
+ ```
271
+ [ A ] Approve [ E ] Edit [ C ] Cancel
272
+ ```
273
+
274
+ Nothing is written until you approve.
275
+
276
+ ---
277
+
278
+ ### `/eng.work` · Execute
279
+
280
+ ```
281
+ /eng.work
282
+ ```
283
+
284
+ APEX executes the approved plan. The **Live Diff panel** updates in real time as files change across every repo. The AI runs tests as it goes, self-corrects on failures (up to 3 attempts per task), and records every architectural decision it makes.
285
+
286
+ You can watch, step away, or answer questions if prompted.
40
287
 
41
- **What runs locally**: the `apex` binary, a native in-process AI runtime engine, and your repos.
42
- **What lives in the cloud**: codebase RAG, episodic session memory, org config, LLM proxy with context injection.
288
+ ---
289
+
290
+ ### `/eng.pre-pr` · Quality gate
291
+
292
+ ```
293
+ /eng.pre-pr
294
+ ```
295
+
296
+ Before opening PRs, APEX runs a full validation pass across all repos:
297
+ - Unit and integration tests
298
+ - Type checking
299
+ - Lint
300
+ - Cross-repo dependency consistency
301
+
302
+ Failures are auto-fixed. You receive a scored quality report with a pass/fail verdict.
303
+
304
+ ---
305
+
306
+ ### `/eng.pr` · Ship
307
+
308
+ ```
309
+ /eng.pr
310
+ ```
311
+
312
+ APEX opens **one PR per repo**, each with:
313
+ - A description derived from the ticket
314
+ - A summary of what changed and why
315
+ - Cross-repo dependency notes (e.g. `shared-types#42` must merge first)
316
+ - Linear ticket status updated automatically
317
+
318
+ ---
319
+
320
+ ## Session Memory in Practice
321
+
322
+ ```
323
+ Monday 5pm: you close the terminal, task 70% done
324
+ Tuesday 9am: apex session resume <id>
325
+ → AI picks up exactly where it stopped, no re-explaining needed
326
+ ```
327
+
328
+ ---
329
+
330
+ ## Slash Commands Reference
331
+
332
+ | Command | Phase | What it does |
333
+ |---|---|---|
334
+ | `/init-apex` | Setup | Initialize workspace config and load org context |
335
+ | `/warm-up` | Daily | Load git status, decisions, and workspace summary |
336
+ | `/eng.start ENG-XX` | Investigate | Fetch ticket, search codebase, produce investigation |
337
+ | `/eng.plan` | Plan | Generate phased cross-repo implementation plan |
338
+ | `/eng.work` | Implement | Execute approved plan across all repos |
339
+ | `/eng.pre-pr` | Validate | Tests, lint, type check, auto-fix failures |
340
+ | `/eng.pr` | Ship | Open one PR per repo, update Linear ticket |
341
+ | `/eng.debug` | Debug | Root-cause analysis and incident investigation |
342
+ | `/eng.review` | Review | Review current diff and staged changes |
343
+ | `/eng.docs` | Document | Update technical docs and READMEs |
344
+ | `/qa-gate` | QA | Full quality gate with numeric scoring |
345
+
346
+ ---
347
+
348
+ ## CLI Reference
349
+
350
+ ```bash
351
+ apex # Open workspace selector and launch
352
+ apex login # Authenticate with GitHub
353
+ apex logout # Remove stored credentials
354
+ apex auth linear # Connect Linear via OAuth
355
+ apex init # Register current repo in a workspace
356
+ apex index # Index workspace repos for semantic search
357
+ apex index --repo backend # Index a specific repo only
358
+ apex index --full # Force full re-index (clears previous)
359
+ apex doctor # Run pre-flight health checks
360
+ apex session list # List paused sessions
361
+ apex session resume <id> # Resume a paused session
362
+ apex workspace list # List all workspaces
363
+ apex workspace edit <name> # Add or remove repos from a workspace
364
+ apex knowledge add <path> # Upload docs/ADRs to org knowledge base
365
+ apex knowledge search <query> # Semantic search over knowledge base
366
+ apex usage # Show token consumption by model/provider
367
+ apex decisions # Show saved architectural decisions
368
+ apex logs # Tail the latest AI engine log
369
+ apex version # Print version
370
+ ```
371
+
372
+ ---
373
+
374
+ ## Common Questions
375
+
376
+ **Q: Does APEX create any files in my repos?**
377
+ Two files, both intentional. `/init-apex` creates `ENV.md` — a workspace environment reference that should go in `.gitignore`. It also creates `AGENTS.md` — an AI context file that should be committed to the repo so the AI understands the codebase conventions. Beyond these, no configuration, state, or lock files are ever created in your repos.
378
+
379
+ **Q: Do I need to re-explain my codebase every session?**
380
+ No. APEX indexes your code semantically and stores structured session summaries. Both are injected automatically into every LLM call. After months of work, APEX still knows why things were built the way they were.
381
+
382
+ **Q: What if a task spans 4 repos?**
383
+ Register all 4 with `apex init`. APEX operates across all of them in every session. The plan, code changes, and PRs span all repos automatically.
384
+
385
+ **Q: Can I start a task without a Linear ticket?**
386
+ Yes. Describe the task in plain English directly in the TUI:
387
+ ```
388
+ › add rate limiting to the payments API, 100 req/min per user
389
+ ```
390
+
391
+ **Q: How do I pause mid-task and resume tomorrow?**
392
+ Close the terminal (Ctrl+C). APEX automatically generates a structured session summary. Tomorrow, run `apex session resume <id>` and the AI picks up exactly where it left off.
393
+
394
+ **Q: What happens if a test fails during `/eng.work`?**
395
+ APEX auto-corrects up to 3 times per failure, trying different strategies. If it can't resolve it, it surfaces a recovery report explaining what it tried and what's blocked.
396
+
397
+ ---
43
398
 
44
399
  ## Links
45
400
 
46
- - [Homepage](https://github.com/Inventeer/apex)
401
+ - [GitHub](https://github.com/Inventeer/apex)
47
402
  - [Documentation](https://github.com/Inventeer/apex/tree/main/docs)
403
+ - [Get Started Guide](https://github.com/Inventeer/apex/blob/main/docs/get-started.md)
48
404
  - [Releases](https://github.com/Inventeer/apex-releases/releases)
49
- - [Issues](https://github.com/Inventeer/apex/issues)
405
+ - [Issues & Feedback](https://github.com/Inventeer/apex/issues)
406
+
407
+ ---
50
408
 
51
409
  ## License
52
410
 
53
- MIT
411
+ MIT © [Inventeer](https://github.com/Inventeer)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@inventeer.tech/apex",
3
- "version": "0.2.31",
3
+ "version": "0.2.33",
4
4
  "description": "AI-powered software delivery agent",
5
5
  "bin": {
6
6
  "apex": "./bin/apex"