Skip to content

skill · phase: ideation

First Activation — Project Discovery

Purpose

When AIDLC is freshly installed in an existing (brownfield) project, this skill runs once to build project context automatically. It replaces the need for the user to run aidlc discover from the terminal.

Activation Condition

Activate this skill before any other AIDLC skill when ALL of the following are true:

  1. AIDLC skills are installed (.aidlc/skills/ exists)
  2. The context directory is missing or empty (.aidlc/context/ does not exist, or contains no .md files)
  3. The user has just sent a message (any message — they may be asking to fix a bug, add a feature, etc.)

If .aidlc/context/ already contains at least one .md file, skip this skill entirely and proceed with the user's request using the appropriate skill.

Behavior

Step 1: Acknowledge and Scan

Tell the user briefly that you're indexing the project for the first time. Keep it short — don't block them with a wall of text.

Example: "First time here — let me scan the project quickly so I have context."

Then perform a lightweight scan:

  1. Read manifest files at the project root: package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, build.gradle, Gemfile, or equivalent.
  2. List top-level directories to understand the project structure.
  3. Sample 3-5 source files from the primary source directory to detect:
    • Indentation style (tabs, 2-space, 4-space)
    • Naming convention (camelCase, snake_case, PascalCase)
    • Import style (grouped vs ungrouped)
  4. Identify the tech stack: language(s), frameworks, test runner, build tool, linter.

Step 2: Ask About Extra Context Folders

After scanning, ask the user:

"I've got the basics — [summarize: language, framework, structure in one line].

Beyond the source code, are there any folders I should be aware of for ongoing context? For example: specs, roadmap, architecture decisions, API schemas, design docs, etc."

Wait for the user's answer. Common examples:

  • specs/, docs/, roadmap/, architecture/, adr/, design/, api/
  • The user might also point to specific files like ARCHITECTURE.md or openapi.yaml

If the user says "no" or "that's it," proceed without extra folders.

Step 3: Read Extra Context

For each folder or file the user mentions:

  1. List its contents (non-recursive, top level only for folders)
  2. Read key files (prefer: index files, READMEs, YAML/JSON schemas, markdown docs)
  3. Summarize what you found — don't copy entire documents verbatim

Cap this step: read at most 10 files total from extra context folders. If there's more, note what was skipped and tell the user they can point you at specific files later.

Step 4: Write Context Documents

Create .aidlc/context/ and write:

style-guide.md

---
generated_by: aidlc-first-activation
generated_at: <ISO 8601 UTC>
---
# Style Guide

## Languages
<table of languages with approximate file counts>

## Conventions
- Indentation: <detected>
- Naming: <detected>
- Import style: <detected>

## Frameworks & Tools
<list of detected frameworks, test runners, build tools>

architecture.md

---
generated_by: aidlc-first-activation
generated_at: <ISO 8601 UTC>
---
# Architecture Overview

## Tech Stack
<primary languages and frameworks>

## Directory Structure
<role mapping of top-level directories>

## Entry Points
<detected entry points>

## Configuration
<config approach: env vars, YAML, etc.>

project-knowledge.md (only if the user provided extra folders)

---
generated_by: aidlc-first-activation
generated_at: <ISO 8601 UTC>
source_paths:
  - <path1>
  - <path2>
---
# Project Knowledge

## Sources
<list of folders/files the user pointed to>

## Summary

### <Folder/File 1 Name>
<2-5 sentence summary of what's in there and what's relevant>

### <Folder/File 2 Name>
<2-5 sentence summary>

## Key References
<specific files worth reading in full when working on related areas>

Step 5: Confirm and Continue

After writing the context docs, briefly confirm:

"Done — indexed the project. Context saved to .aidlc/context/. Now, back to your request..."

Then immediately proceed with whatever the user originally asked. Do not make them repeat themselves. Their original message is still the active task — discovery was a transparent preamble.

Important Notes

  • This skill runs exactly once per project. After context docs are written, it never triggers again.
  • Don't over-scan. This is a lightweight pass, not a full AST analysis. 3-5 sampled files is enough for style detection.
  • Don't block the user. The scan should feel like a 10-second preamble, not a separate workflow. If the project is huge, just scan what you can quickly and note gaps.
  • Respect .gitignore patterns. Don't scan node_modules/, dist/, build/, .git/, etc.
  • Extra context is optional. If the user says "nah, just the code" — that's fine. Skip project-knowledge.md.
  • The user's original request takes priority. Discovery enables better answers but must not derail the conversation.

Exit Criteria

  • .aidlc/context/style-guide.md exists with detected conventions
  • .aidlc/context/architecture.md exists with structure overview
  • .aidlc/context/project-knowledge.md exists (if extra folders were provided)
  • The user's original request is being addressed (not abandoned)