create-chat-gpt-repo-memory 0.1.0

package/src/paths.js

@@ -0,0 +1,21 @@
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { stat } from "node:fs/promises";
+
+export async function resolveTargetDirectory(cwd) {
+  const resolved = resolve(cwd);
+  let stats;
+  try {
+    stats = await stat(resolved);
+  } catch {
+    throw new Error(`Target directory does not exist: ${resolved}`);
+  }
+  if (!stats.isDirectory()) {
+    throw new Error(`Target path is not a directory: ${resolved}`);
+  }
+  return resolved;
+}
+
+export function getPackageRoot() {
+  return dirname(dirname(fileURLToPath(import.meta.url)));
+}

package/src/projectName.js

@@ -0,0 +1,5 @@
+import path from "node:path";
+
+export function getProjectName(rootDir) {
+  return path.basename(path.resolve(rootDir));
+}

package/src/templateResolver.js

@@ -0,0 +1,27 @@
+export const SUPPORTED_TEMPLATES = ["generic", "dotnet"];
+
+export function validateTemplateName(templateName) {
+  if (!SUPPORTED_TEMPLATES.includes(templateName)) {
+    throw new Error(
+      `Unsupported template "${templateName}". Supported templates: ${SUPPORTED_TEMPLATES.join(", ")}.`
+    );
+  }
+}
+
+export function applyTemplateVariables(content, variables) {
+  let rendered = content;
+
+  for (const [key, value] of Object.entries(variables)) {
+    const pattern = new RegExp(`\\{\\{${key}\\}\\}`, "g");
+    rendered = rendered.replace(pattern, value);
+  }
+
+  const unreplaced = rendered.match(/\{\{[^}]+\}\}/g);
+  if (unreplaced) {
+    throw new Error(
+      `Template contains unreplaced placeholders: ${Array.from(new Set(unreplaced)).join(", ")}.`
+    );
+  }
+
+  return rendered;
+}

package/templates/dotnet/AGENTS.md

@@ -0,0 +1,129 @@
+# Agent Instructions for {{PROJECT_NAME}}
+
+Before answering project-specific questions:
+
+1. Read `.agent-memory/project-map.md`.
+2. Use the project map to identify the relevant domain, files, and conventions.
+3. Read only the specific files needed for the task.
+4. Do not scan generated, build, cache, vendor, or dependency folders unless explicitly asked.
+5. Prefer existing project patterns over introducing new architecture.
+6. When changing code, identify tests or validation steps that should be added or updated.
+7. When discovering important durable project facts, update the most specific relevant file under `.agent-memory/`.
+
+## Project Memory Workflow
+
+Use this order for project-specific work:
+
+1. Read `.agent-memory/project-map.md`.
+2. Read `.agent-memory/architecture.md` if the task involves architecture, layering, dependency flow, integrations, or background processing.
+3. Read `.agent-memory/conventions.md` before making code-style, testing, logging, naming, or pattern decisions.
+4. Read `.agent-memory/workflows.md` before changing build, test, deployment, database, release, or operational workflows.
+5. Read source files only after narrowing the task to the relevant area.
+
+## Project Memory Update Rule
+
+After making changes, decide whether the change affects durable project knowledge.
+
+Update `.agent-memory/` files only when the change affects:
+
+- repository structure
+- architecture
+- major domains
+- entry points
+- dependency flow
+- data access
+- external integrations
+- build, test, deployment, or release workflow
+- coding conventions
+- operational concerns
+- known gotchas
+
+Do not update project memory for small local implementation changes.
+
+When updating memory:
+
+1. Update the most specific file possible.
+2. Keep `.agent-memory/project-map.md` concise.
+3. Do not duplicate source code.
+4. Do not include secrets.
+5. If memory files conflict with current code, trust the current code and update memory.
+6. Mark uncertain items as `Needs verification`.
+
+## Multi-Agent / Multi-Session Rule
+
+Treat `.agent-memory/` as shared project documentation.
+
+If multiple agents or sessions are working on the same project:
+
+- Keep memory changes in the same branch as the related code change.
+- Do not update `.agent-memory/project-map.md` unless the high-level project index changed.
+- Prefer updating detailed supporting files instead of the top-level project map.
+- Resolve memory conflicts like documentation:
+  - keep facts that match current code
+  - remove stale facts
+  - keep shorter wording when both versions are correct
+  - mark uncertain items as `Needs verification`
+
+## .NET-Specific Guidance
+
+- Prefer existing dependency injection patterns.
+- Check project files (`*.csproj`) before adding packages.
+- Look for solution files (`*.sln`) to understand project boundaries.
+- Identify test framework before writing tests.
+- Do not assume EF Core, EF6, Dapper, or raw ADO.NET without checking the code.
+- Be careful with generated database-first files.
+- Do not scan `bin/`, `obj/`, `.vs/`, or generated EF files unless directly relevant.
+
+## Do Not Scan By Default
+
+Do not scan these unless directly relevant:
+
+- `.git/`
+- `bin/`
+- `obj/`
+- `node_modules/`
+- `vendor/`
+- `dist/`
+- `build/`
+- `target/`
+- `out/`
+- `.next/`
+- `.nuxt/`
+- `.turbo/`
+- `.cache/`
+- `.pytest_cache/`
+- `__pycache__/`
+- `.venv/`
+- `venv/`
+- `.gradle/`
+- `.vs/`
+- `.idea/`
+- `.vscode/`
+- `coverage/`
+- generated files
+- package/cache folders
+- local environment folders
+
+## Project Memory Files
+
+Project context is stored in:
+
+- `.agent-memory/project-map.md`
+- `.agent-memory/architecture.md`
+- `.agent-memory/conventions.md`
+- `.agent-memory/workflows.md`
+- `.agent-memory/update-project-map.md`
+
+## Kickoff Prompts
+
+Initial map fill:
+
+```text
+Use AGENTS.md as your operating instructions for this repository. Then read .agent-memory/prompts/fill-project-map.md and execute it. Fill or update the .agent-memory files using only verified repository facts. Do not include secrets.
+```
+
+Future session start:
+
+```text
+Use AGENTS.md as your operating instructions, then read .agent-memory/prompts/start-session.md and follow it for this task.
+```

package/templates/dotnet/architecture.md

@@ -0,0 +1,47 @@
+# Architecture: {{PROJECT_NAME}}
+
+## High-Level Architecture
+
+Needs verification.
+
+## Major Layers or Components
+
+Needs verification.
+
+## Dependency Flow
+
+Needs verification.
+
+## Data Flow
+
+Needs verification.
+
+## External Integrations
+
+Needs verification.
+
+## Background, Scheduled, or Async Work
+
+Needs verification.
+
+## Data Storage and State Management
+
+Needs verification.
+
+## Error Handling and Logging
+
+Needs verification.
+
+## Security and Secrets Handling
+
+Needs verification.
+
+Do not include secrets, credentials, tokens, private keys, connection strings, or sensitive values.
+
+## Performance or Scalability Notes
+
+Needs verification.
+
+## Architectural Risks or Unclear Areas
+
+Needs verification.

package/templates/dotnet/conventions.md

@@ -0,0 +1,69 @@
+# Conventions: {{PROJECT_NAME}}
+
+## Naming Conventions
+
+Needs verification.
+
+## Project Organization
+
+Needs verification.
+
+## Dependency Management
+
+Needs verification.
+
+## Application Structure
+
+Needs verification.
+
+## Testing Conventions
+
+Needs verification.
+
+## Logging Conventions
+
+Needs verification.
+
+## Error Handling Conventions
+
+Needs verification.
+
+## Data Access Conventions
+
+Needs verification.
+
+## API or Interface Conventions
+
+Needs verification.
+
+## Frontend or UI Conventions
+
+Needs verification.
+
+## Infrastructure Conventions
+
+Needs verification.
+
+## Documentation Conventions
+
+Needs verification.
+
+## C# Conventions
+
+Needs verification.
+
+## Dependency Injection Conventions
+
+Needs verification.
+
+## Async and CancellationToken Conventions
+
+Needs verification.
+
+## Entity Framework / Data Access Conventions
+
+Needs verification.
+
+## MSTest / xUnit / NUnit Conventions
+
+Needs verification.

package/templates/dotnet/project-map.md

@@ -0,0 +1,104 @@
+# Project Map: {{PROJECT_NAME}}
+
+Generated by: {{GENERATED_BY}}  
+Template: {{TEMPLATE_NAME}}
+
+## Purpose
+
+Needs verification.
+
+## Tech Stack
+
+Needs verification.
+
+Include languages, frameworks, runtimes, package managers, databases, infrastructure, and major tools only after verifying from repository files.
+
+## Repository Layout
+
+Needs verification.
+
+Summarize important folders and what they contain.
+
+## Entry Points
+
+Needs verification.
+
+Include application startup files, command-line entry points, background jobs, scheduled jobs, services, scripts, frontend entry points, test entry points, or infrastructure entry points as applicable.
+
+## Major Domains
+
+Needs verification.
+
+For each major business or technical domain, capture:
+
+- Purpose
+- Important files, classes, modules, packages, or services
+- Related data stores, schemas, queues, APIs, jobs, or external systems if obvious
+- Known gotchas
+
+## Dependency Injection
+
+Needs verification.
+
+## Database and Entity Mapping
+
+Needs verification.
+
+## Critical Files
+
+Needs verification.
+
+List only files that future agent sessions should know about early.
+
+## Configuration and Secrets
+
+Needs verification.
+
+Describe where configuration appears to come from.
+
+Do not include secrets, credentials, tokens, private keys, connection strings, or sensitive values.
+
+## Data and State
+
+Needs verification.
+
+Describe databases, file storage, queues, caches, state machines, migrations, schemas, APIs, or other stateful systems if discoverable.
+
+## Testing and Validation
+
+Needs verification.
+
+Describe test frameworks, test locations, validation commands, linting, formatting, type checking, QA workflows, or manual validation steps if discoverable.
+
+## Build, Run, and Deployment
+
+Needs verification.
+
+Describe package managers, build commands, runtime commands, deployment files, CI/CD, release workflow, environment behavior, or operational concerns if discoverable.
+
+## .NET Projects
+
+Needs verification.
+
+For each project, capture:
+
+- Project path
+- Project type
+- Target framework
+- Main responsibility
+- Important package references
+
+## Do Not Scan By Default
+
+- `.git/`
+- dependency folders
+- build output folders
+- generated files
+- package/cache folders
+- IDE/editor folders
+- coverage/report folders
+- local environment folders
+
+## Known Gotchas
+
+Needs verification.

package/templates/dotnet/prompts/fill-project-map.md

@@ -0,0 +1,50 @@
+# Fill Project Map Prompt
+
+Inspect this repository and fill in the repo memory files.
+
+Start with:
+
+- `AGENTS.md`
+- `.agent-memory/project-map.md`
+- `.agent-memory/architecture.md`
+- `.agent-memory/conventions.md`
+- `.agent-memory/workflows.md`
+- `.agent-memory/update-project-map.md`
+
+## Goal
+
+Create a concise, durable project memory that helps future ChatGPT/Codex-style coding sessions understand this repository without repeatedly scanning the entire codebase.
+
+## Rules
+
+- Start with `.agent-memory/project-map.md`.
+- Keep `.agent-memory/project-map.md` concise enough to be useful at the beginning of a future coding session.
+- Move detailed explanations into `.agent-memory/architecture.md`, `.agent-memory/conventions.md`, and `.agent-memory/workflows.md`.
+- Do not scan generated, build, cache, vendor, dependency, IDE, coverage, or local environment folders unless directly relevant.
+- Do not include secrets, credentials, tokens, private keys, connection strings, or sensitive values.
+- Mark uncertain items as `Needs verification`.
+- Do not invent facts.
+- Prefer facts grounded in repository files over guesses.
+- When finished, summarize files updated, domains discovered, unclear areas, and suggested next improvements.
+
+## Suggested Scan Order
+
+1. Top-level README and documentation
+2. Workspace, solution, package, manifest, or project files
+3. Application startup, command, service, or entry-point files
+4. Configuration files, without exposing secret values
+5. Main source folders
+6. Test or validation folders
+7. Build, CI/CD, deployment, infrastructure, or release files
+8. Scripts and operational tooling
+
+## .NET-Specific Scan Order
+
+1. `*.sln`
+2. `*.csproj`
+3. `Program.cs`, `Startup.cs`, hosted services, worker services
+4. Dependency injection registration files
+5. Configuration files, without exposing secret values
+6. DbContext, repositories, database-first generated models, SQL scripts
+7. Test projects
+8. CI/CD and deployment scripts

package/templates/dotnet/prompts/start-session.md

@@ -0,0 +1,30 @@
+# Start Session Prompt
+
+Use `AGENTS.md` as your operating instructions for this repository.
+
+Then read:
+
+- `.agent-memory/project-map.md`
+- `.agent-memory/architecture.md` if the task involves architecture, layering, dependency flow, integrations, or background processing
+- `.agent-memory/conventions.md` if the task involves coding patterns, tests, naming, logging, or style
+- `.agent-memory/workflows.md` if the task involves build, test, deployment, release, data, or operational workflows
+
+Use the project map to narrow the task before reading source files.
+
+Do not scan the entire repository unless necessary.
+
+Do not scan generated, build, cache, vendor, dependency, IDE, coverage, or local environment folders unless directly relevant.
+
+Do not include secrets, credentials, tokens, private keys, connection strings, or sensitive values in responses or memory files.
+
+If you discover durable project knowledge, update the most specific relevant file under `.agent-memory/`.
+
+If project memory conflicts with current code, trust the current code and update the memory.
+
+## .NET Session Notes
+
+For .NET repositories, check solution and project boundaries before making changes.
+
+Prefer existing dependency injection, logging, configuration, test, and data-access patterns.
+
+Do not assume a specific data access technology until verified from repository files.

package/templates/dotnet/update-project-map.md

@@ -0,0 +1,61 @@
+# Updating the Project Map
+
+Use this file as maintenance guidance for repo memory.
+
+## When to Update
+
+Update `.agent-memory/` memory files when discovering or changing durable project facts such as:
+
+- New major domains
+- Important entry points
+- Critical files
+- Non-obvious configuration behavior
+- Data access or state management patterns
+- External integrations
+- Testing or validation conventions
+- Build, deployment, release, or operational behavior
+- Known gotchas
+- Significant architecture or dependency-flow changes
+
+Do not update project memory for every code change.
+
+## Where to Update
+
+Use the most specific file possible:
+
+- `.agent-memory/project-map.md` for concise high-level index changes
+- `.agent-memory/architecture.md` for architecture, dependency flow, data flow, and integration design
+- `.agent-memory/conventions.md` for coding, naming, testing, logging, and organization patterns
+- `.agent-memory/workflows.md` for build, test, validation, deployment, release, debugging, and operational steps
+
+## Multi-Agent Memory Updates
+
+When multiple agents are working concurrently:
+
+- Do not update `.agent-memory/project-map.md` unless the high-level project index changed.
+- Keep memory changes in the same branch as the code change that caused them.
+- If a memory file conflicts during merge, resolve it like documentation:
+  - keep facts that match current code
+  - remove stale facts
+  - keep the shorter wording when both are correct
+  - mark uncertain items as `Needs verification`
+
+## Rules
+
+- Keep summaries short and useful.
+- Do not duplicate entire source files.
+- Do not include secrets, credentials, tokens, private keys, connection strings, or sensitive values.
+- Mark uncertain items as `Needs verification`.
+- Do not invent facts.
+- Prefer facts grounded in repository files over guesses.
+- Remove stale statements when contradicted by code.
+- Move detailed explanations out of `.agent-memory/project-map.md` and into supporting memory files.
+
+## Maintenance Workflow
+
+1. Read `.agent-memory/project-map.md`.
+2. Inspect only the relevant project files.
+3. Decide whether durable project knowledge changed.
+4. If yes, update the smallest relevant memory section.
+5. Keep the top-level project map concise.
+6. Add detailed notes to supporting memory files when needed.

package/templates/dotnet/workflows.md

@@ -0,0 +1,67 @@
+# Workflows: {{PROJECT_NAME}}
+
+## Add a New Feature
+
+Needs verification.
+
+## Add or Update a Test
+
+Needs verification.
+
+## Trace a Bug
+
+Needs verification.
+
+## Modify Data or State-Related Code
+
+Needs verification.
+
+## Work With Configuration and Secrets
+
+Needs verification.
+
+Do not include secrets, credentials, tokens, private keys, connection strings, or sensitive values.
+
+## Update External Integrations
+
+Needs verification.
+
+## Build and Run Locally
+
+Needs verification.
+
+## Validate Before Commit
+
+Needs verification.
+
+## Deployment or Release
+
+Needs verification.
+
+## Rollback or Recovery
+
+Needs verification.
+
+## Add a .NET Service
+
+Needs verification.
+
+## Add or Update a Unit Test
+
+Needs verification.
+
+## Add or Update Database Access
+
+Needs verification.
+
+## Check Build
+
+Needs verification.
+
+Potential commands, verify before use:
+
+```bash
+dotnet restore
+dotnet build
+dotnet test
+```