alkdev/taskgraph_ts
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add architecture doc and research reports for taskgraph_ts napi wrapper

Browse Source
This commit is contained in:
glm-5.1
2026-04-23 10:30:40 +00:00
parent 1517b5459e
commit ba8c382d53
5 changed files with 3566 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

172
docs/research/taskgraph_ts_current_state.md Normal file
View File

@@ -0,0 +1,172 @@
# TaskGraph_TS — Current State Research Report
**Date:** 2026-04-23
**Repository:** git@git.alk.dev:alkdev/taskgraph_ts.git
**Branch:** main
**Commit:** 1517b54 ("inital setup")
---
## 1. File Structure
The repository is in an extremely early, freshly-initialized state. The entire non-git content consists of only two files:
```
/workspace/@alkdev/taskgraph_ts/
├── .git/ # Git repository data
├── AGENTS.md # Agent/instructions file (32 lines)
└── docs/
└── research/
└── .gitkeep # Empty placeholder to keep directory in git
```
That is the **complete** file tree. There are no source files, no configuration files, no tests, no documentation beyond what is listed above.
---
## 2. Configuration Files
### What exists
| File | Status |
|---|---|
| `package.json` | **Does not exist** |
| `tsconfig.json` | **Does not exist** |
| `Cargo.toml` | **Does not exist** |
| `tslint.json` / `.eslintrc*` | **Does not exist** |
| `.prettierrc*` | **Does not exist** |
| `.gitignore` | **Does not exist** |
| `.editorconfig` | **Does not exist** |
| `README.md` | **Does not exist** |
| `LICENSE` | **Does not exist** |
| Any Makefile / build script | **Does not exist** |
### Summary
There are **zero configuration files** in the repository. No package manager is initialized. No TypeScript compiler configuration exists. No linters, formatters, or CI/CD pipelines have been set up. The project name `taskgraph_ts` implies a TypeScript project, but no `package.json` or `tsconfig.json` has been created yet.
---
## 3. Existing Code / Boilerplate
There is **no source code** in the repository. No `src/` directory exists. No `lib/`, `bin/`, `test/`, or `examples/` directories exist. No `.ts`, `.js`, `.rs`, or any other source files are present.
The only non-git file with actual content is `AGENTS.md`, which is a meta-tool instruction file (not project code). The only other file is `docs/research/.gitkeep`, which is an empty placeholder.
---
## 4. AGENTS.md File Contents
The `AGENTS.md` file is 32 lines long and contains instructions for AI agent memory/tool usage. Full content:
```markdown
## Memory Tools
You have access to two tools for managing your context and accessing session history:
### memory({tool: "...", args: {...}})
Read-only tool for introspecting your session history and context state. Available operations:
- `memory({tool: "help"})` — full reference with examples
- `memory({tool: "summary"})` — quick counts of projects, sessions, messages, todos
- `memory({tool: "sessions"})` — list recent sessions (useful for finding past work)
- `memory({tool: "messages", args: {sessionId: "..."}})` — read a session's conversation
- `memory({tool: "search", args: {query: "..."}})` — search across all conversations
- `memory({tool: "compactions", args: {sessionId: "..."}})` — view compaction checkpoints
- `memory({tool: "context"})` — check your current context usage
### memory_compact()
Trigger compaction on the current session. This summarizes the conversation so far to free context space.
**When to use memory_compact:**
- When context is above 80% (check with `memory({tool: "context"})`)
- When you notice you're losing track of earlier conversation details
- At natural breakpoints in multi-step tasks (after completing a subtask, before starting a new one)
- When the system prompt shows a yellow/red/critical context warning
- Proactively, rather than waiting for automatic compaction at 92%
**When NOT to use memory_compact:**
- When context is below 50% (it wastes a compaction cycle)
- In the middle of a complex edit that you need immediate context for
- When the task is nearly complete (just finish the task instead)
Compaction preserves your most important context in a structured summary — you will continue the session with the summary as your starting point.
```
This file is **not** project-specific documentation — it is a shared instruction set for AI coding agents describing how to use memory introspection and compaction tools. It contains no information about the `taskgraph_ts` project's design, architecture, or goals.
---
## 5. Documentation and Design Notes
There is **no project documentation** in the repository. Key absences:
- No `README.md` describing the project
- No design documents or architecture notes
- No ADRs (Architecture Decision Records)
- No API specifications
- No diagrams or schematics
- The `docs/research/` directory exists but contains only an empty `.gitkeep` file — it was created as a placeholder for future research documents (like this one)
---
## 6. Git History
### Full Git Log
```
1517b54 inital setup
```
There is exactly **one commit** in the repository, authored on 2026-04-23:
| Field | Value |
|---|---|
| **Commit** | `1517b5459e1d79388a96057d17a72ac53064a068` |
| **Author** | glm-5.1 <glm-5.1@alk.dev> |
| **Date** | Thu Apr 23 08:13:39 2026 +0000 |
| **Message** | "inital setup" (note: typo — "inital" instead of "initial") |
### Files in that commit
| File | Change |
|---|---|
| `AGENTS.md` | Added (32 lines) |
| `docs/research/.gitkeep` | Added (empty file) |
### Branches
| Branch | Status |
|---|---|
| `main` (local) | Current branch, up to date with remote |
| `remotes/origin/main` | Remote tracking branch |
### Remote
```
origin git@git.alk.dev:alkdev/taskgraph_ts.git (fetch)
origin git@git.alk.dev:alkdev/taskgraph_ts.git (push)
```
### Working tree status
Clean — no uncommitted changes, no untracked files.
---
## Summary and Key Observations
1. **This is a blank-slate project.** The repository was just initialized with a single commit containing only an agent instructions file and an empty directory placeholder. No code, configuration, or documentation has been written yet.
2. **The project name implies TypeScript.** `taskgraph_ts` strongly suggests a TypeScript implementation of a "task graph" — likely a DAG (Directed Acyclic Graph) based task scheduling/execution system. However, no TypeScript tooling (`package.json`, `tsconfig.json`) has been set up.
3. **No `.gitignore` exists.** This should be created before adding any source files to avoid accidentally committing `node_modules/`, build artifacts, etc.
4. **No README or design docs.** There are no records of the project's purpose, scope, or intended architecture. Any future work will need to define these from scratch.
5. **The `docs/research/` directory** was explicitly created as a placeholder, suggesting the project founders intended for research documentation to be generated — which is what this report fulfills.
6. **Single author so far.** The only commit was by `glm-5.1@alk.dev`, an AI agent, indicating the project was initialized programmatically.
7. **Everything needs to be built from scratch:** package initialization, TypeScript configuration, source code structure, testing framework, linting/formatting, CI/CD, documentation, and the actual task graph implementation itself.