agentleFS
joelaharris98joelaharris98/legal-ai-engineering-lab/.agents/skills/start-project/SKILL.md

start-project

Skill2 starsChanged 3 months agoMITView on GitHub

Automatically use when the owner introduces a new legal-tech idea, wants to streamline a legal workflow, begins a new feature/product/automation, or is unsure what to build first. Also use for a first session in a fresh clone — "what is this?", "where do I start?", "I've just cloned this" — which needs orientation rather than discovery (section 0). Also use when an existing idea is being materially reframed, or when an idea turns out to be too large to settle in one conversation and needs its open questions mapped before anything is built. Guide workflow discovery and define the smallest useful first experiment before substantial implementation. Do not use for continuing work on an idea that has already been framed, for small additions inside an existing experiment, or for ordinary coding tasks.

10 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use write-tests and commit.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • SentrySkill

    write-tests

    Write tests following project conventions. Use when adding new tests or modifying existing ones.

    Also in 3 projects that use this

  • SentrySkill

    commit

    Create commit messages following Sentry conventions. Use when committing code changes, writing commit messages, or formatting git history. Follows conventional commits with Sentry-specific issue references.

    Also in 3 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

28 rules. 0 are common, 23 are distinctive, and 5 are very specific to this project.

  • 0

    Common

    Most of the 9 edited versions we read keep these.

  • 23

    Distinctive

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this skill to turn the owner's idea into a clear, testable first piece of work without taking ownership of the idea away from them.

    line 11
  2. Distinctive:

    Follow all mentoring and safety rules in AGENTS.md (which CLAUDE.md imports).

    line 15
  3. Distinctive:

    Keep it short. A tour of the directory structure is not orientation.

    line 67
  4. Distinctive:

    Start in ordinary language.

    line 73
  5. Distinctive:

    Do not turn this into a long questionnaire.

    line 87
  6. Distinctive:

    Ask in rounds, not one at a time: Put every question you can ask *now* in a single numbered round, then wait for the answers.

    line 100
  7. Distinctive:

    Finding facts is your job, never the owner's: If a question can be settled by reading the repository, checking whether a format parses, or …

    line 108
  8. Distinctive:

    Challenge fuzzy vocabulary as it arises: When a word is doing two jobs, say so immediately: "you have used *deadline* for both a date the …

    line 114
  9. Distinctive:

    Do not assume an LLM is required because the project concerns legal AI.

    line 150
  10. Distinctive:

    If a deterministic solution is better, say so and explain why.

    line 159
  11. Distinctive:

    Ask what must be proven before it is sensible to build more.

    line 163
  12. Distinctive:

    Then count them: If there is one dominant uncertainty, continue to section 5 and design an experiment that tests it.

    line 176
  13. Very specific:

    Do not charge at it. Chart what is unknown, then answer one question at a time and let each answer show you the next.

    line 189
  14. Distinctive:

    Not the product — the decision or evidence this effort is heading towards.

    line 200
  15. Distinctive:

    Write down only the questions you can phrase precisely today.

    line 207
  16. Distinctive:

    When a question is answered: record one line in Decisions so far pointing at wherever the detail actually lives — the experiment README, …

    line 236
  17. Distinctive:

    Do not start building during this phase.

    line 249
  18. Distinctive:

    Use synthetic or public data by default.

    line 275
  19. Distinctive:

    Create or update the appropriate project/experiment brief from the repository templates.

    line 279
  20. Very specific:

    One file, inside the experiment: Not a directory, not a module, not a place to put things later — but in experiments/<nnn>-<name>/ from the …

    line 332
  21. Distinctive:

    Do not front-load a software-engineering course.

    line 375
  22. Distinctive:

    When the project creates a reason to introduce a concept, explain:

    line 377
  23. Distinctive:

    when it would be unnecessary.

    line 383
  24. Distinctive:

    Use it when the *direction* is genuinely unsettled, not whenever new code is written.

    line 395
  25. Very specific:

    architecture-review: when the experiment is growing, code is being promoted/reused, a new module/service/database/API/framework is …

    line 412
  26. Very specific:

    security-review: when real/confidential data, users, credentials, external providers, databases, permissions, AI tools, or consequential …

    line 413
  27. Very specific:

    learning-review: after a meaningful milestone or architectural decision so the owner consolidates what the project has taught.

    line 415
  28. Distinctive:

    After any review, return to normal building and iteration unless the review identifies a blocker.

    line 418

“Common” is measured: kept by at least 6 in 10 of the 9 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md
<!-- Generated from ../../../.claude/skills/start-project/SKILL.md - do not edit this copy. Edit the source and run `uv run python scripts/sync_agent_files.py`. -->

Start Project

Use this skill to turn the owner's idea into a clear, testable first piece of work without taking ownership of the idea away from them.

The repository owner brings the legal workflow, frustration, or product idea. Your job is to help them understand it, sharpen it, and begin building it in a way that teaches useful legal-engineering judgement.

Follow all mentoring and safety rules in AGENTS.md (which CLAUDE.md imports).

This skill drives phases A to C of docs/WORKING_PROCESS.md, which maps the whole shape an idea moves through and names what owns each later phase.

0. A first session, where there is no idea yet

Someone who has just cloned this and asks "what is this?" or "where do I start?" has not given you a project to frame. Everything below assumes an idea; this branch exists to produce one. Do not run sections 1 to 6 on somebody who has not yet said what their work looks like.

Check the three things the repository relies on, first

A fresh clone can be missing its environment, and one of the two safety controls is opt-in. Neither absence announces itself: the commit guard is simply not installed, and the pre-read guard fails open if uv is missing. So check before anything else — in one line to the owner, not as an audit:

Before we start, I'm checking the three things this repository relies on — uv, the installed environment, and the commit-safety hook.

CheckCommandIf it fails
uv is installeduv --versionPoint at the install line in README.md. It needs a fresh terminal afterwards, which is the usual reason it looks as though it did not work
The environment existsuv run pytestRun uv sync, then retry
The commit guard is ongit config --get core.hooksPath returns .githooksRun git config core.hooksPath .githooks, and say in one sentence what it now does

Fix what is missing, then move on. Do not narrate the passes, do not explain what a hook is unless one failed, and do not turn this into a tour of the safety model — that material belongs at the moment it applies. Three commands, then orientation.

Then orient them briefly, and in this order:

  1. What the repository is, in two or three sentences. An environment for turning a real legal-workflow problem into experiments and, where justified, into working tools — not a tutorial, and it prescribes no projects.
  2. An offer to walk through experiments/001-deadline-extraction-baseline/ as the shape a piece of work takes here: a real question, synthetic fixtures, labels written before the code ran, a measured result, an honest conclusion.
  3. One question: which part of their working week is slow, repetitive, or error-prone.
  4. And one more, worth its own sentence: what they have already done that touches this — written SQL, run a document review platform, managed a system implementation, built spreadsheets nobody else can maintain. Anyone arriving with that is starting from somewhere specific, and a session that discovers it in week six has wasted five. Record the answer, and the depth claimed, to docs/learning-log/ under criterion 2 of learning-review. It is the cheapest record in the repository to earn and the one that changes the most about what to teach.

Question 3 is what turns orientation into a project, and sections 1 onward take over the moment they answer it.

Keep it short. A tour of the directory structure is not orientation; it is a reason to close the window. Do not list the skills, do not summarise the working policy, and do not ask them to read anything before they have described a problem of their own.

1. Understand the real workflow

Start in ordinary language. Establish only what is necessary to understand:

  • who does the work today;
  • what starts the process;
  • what information goes in;
  • what steps people actually perform;
  • what comes out and where it goes;
  • which parts are slow, repetitive, frustrating, inconsistent, or error-prone;
  • which parts are mechanical;
  • which parts require interpreting language;
  • which parts involve genuine legal judgement or authority;
  • what happens if the process is wrong;
  • how easy the output is for a person to review.

Do not turn this into a long questionnaire. Infer obvious things, state assumptions, and ask only questions that materially alter what should be built.

Summarise the workflow using:

Input → Transformation → Output → Side effect → Risk → Control

Explain why any important distinction matters in plain English.

How to ask

The questions themselves are worth getting right, because a badly framed one either cannot be answered or teaches nothing.

  • Ask in rounds, not one at a time. Put every question you can ask now in a single numbered round, then wait for the answers. A question whose answer depends on another question in the same round belongs in the next round, not this one.
  • Attach your recommended answer to every question. This is the difference between a question the owner can answer and one they cannot. "Where should the results be stored?" is unanswerable without engineering context; "I would write the results to a JSON file for now, because a database would add setup without solving a problem we currently have — does that fit?" is answerable, and it teaches the reasoning rather than testing for it.
  • Finding facts is your job, never the owner's. If a question can be settled by reading the repository, checking whether a format parses, or looking something up, go and settle it. Bring the owner decisions, not homework. The decisions genuinely are theirs: what the workflow really costs, what a colleague would accept, what level of accuracy is worth trusting given what a mistake costs. Do not answer those on their behalf.
  • Challenge fuzzy vocabulary as it arises. When a word is doing two jobs, say so immediately: "you have used deadline for both a date the other side proposed and one that has been agreed — which do you mean here?" In legal technology this is not pedantry. Software inherits whatever ambiguity survives this conversation, and a system that cannot tell a proposed date from an agreed one will eventually put the wrong one in front of a fee earner. Record the resolved term in docs/GLOSSARY.md.

2. Decide whether to build anything, and only then whether AI is useful

There is a question above "should this use AI?", and it is asked less often because it is the one that can end the project. Work down this ladder and stop at the first rung that answers the problem:

  1. Could the workflow itself change? The cheapest automation is often a step nobody needs to perform. A field made mandatory at intake, a template that stops the ambiguity arising, an agreed convention about where the date goes — these fix the cause rather than processing the symptom, and they cost no software at all.
  2. Does something already do this? Practice management systems, document management systems and the firm's existing tooling frequently do more than the people using them know, and there are vendors for most recurring legal workflows. Find out. This is a look-it-up, so it is yours rather than the owner's.
  3. If we build, can ordinary software do it? The rest of this section.
  4. Where does AI genuinely earn its place? Language that has to be interpreted.

Rungs 1 and 2 are not reasons to abandon the experiment. An experiment that establishes "the vendor tool does 80% of this and here is the 20% it misses" is a strong result, and being able to say why you did not build is the judgement these roles are hiring for. But they change what the first experiment should test, and they are much cheaper to ask now than after a fortnight of building.

Two of them are also the owner's to answer rather than yours: whether the workflow could change usually depends on who owns the process, and whether a vendor tool is available may depend on what the firm already licenses. Ask; do not assume.

Then, having decided something is worth building:

Do not assume an LLM is required because the project concerns legal AI.

Separate:

  • predictable mechanical rules that ordinary software can handle reliably;
  • interpretation of messy or ambiguous language where AI may help;
  • legal judgement or authority that should not be casually delegated;
  • actions that change data or affect other people.

If a deterministic solution is better, say so and explain why.

3. Identify what would have to be found out

Ask what must be proven before it is sensible to build more.

Examples:

  • Can the information be extracted reliably?
  • Is the source data structured enough?
  • Can users review the output quickly?
  • Does this actually save meaningful time?
  • Can the model distinguish two legally important categories?
  • Is a normal rule-based approach sufficient?

The first build should test the most important uncertainty, not imitate the final production system.

Then count them. If there is one dominant uncertainty, continue to section 5 and design an experiment that tests it. If there are several, and some of them depend on the answers to others, the honest position is that you cannot yet choose the first experiment — and compressing them into one anyway is the most expensive mistake available here, because it produces weeks of work answering a question that was not blocking anything. Chart the map instead.

4. When the fog is thicker than one conversation

Some ideas arrive whole. "We spend ages preparing bundles" is not one of them: there are several things nobody knows, they depend on each other, and the way from here to a decision is not visible yet.

Do not charge at it. Chart what is unknown, then answer one question at a time and let each answer show you the next. The four map sections in templates/PROJECT_BRIEF.md carry this; create the brief from that template and fill them in.

templates/PROJECT_BRIEF.example.md is one filled in mid-flight, on exactly this bundle example. Offer it rather than describing the sections — a half-charted map is much easier to recognise than to specify, and the owner is being asked to write something they have never seen.

Name the destination first

Not the product — the decision or evidence this effort is heading towards. "A decision on whether automated bundle checking is worth building, supported by a measured result." The destination fixes the scope, so everything else depends on settling it, and it is what tells you later whether a question is on the route or beyond it.

Chart what you can state, and leave the rest as fog

Write down only the questions you can phrase precisely today. The rest — the things you can sense are coming but cannot yet pin down, because they hang on answers you do not have — go in Not yet specified, as loosely as the view allows.

The test for promoting one is whether you can state the question precisely now, not whether you can answer it. A sharp question you are blocked on is an open question; a vague sense that data protection will matter somehow is fog. Do not pre-slice the fog: one vague patch often turns into three questions, or none.

Work that is beyond the destination is not fog. It goes in Out of scope, and it never graduates — it returns only if the destination itself is redrawn.

Give every question a way of being answered

An open question with no route to an answer sits on the list forever. Each one carries how it gets resolved:

TypeWho answers it, and how
Look it upYou do. Does this format parse, does a tool already exist, what does the provider's terms say. Never the owner's homework.
Try itA small experiment. "Can a model tell a proposed deadline from an agreed one?" is only answerable by running it — and it is a finding, so it belongs in experiments/ with the question written down, not in a scratch file.
Decide itThe owner, with options and your recommendation in front of them. Would a fee earner accept this? Is this level of accuracy tolerable given what a miss costs? Put these to them and wait — do not answer them yourself.
Not ours to settleThe fact belongs to an organisation, and this project does not have one. Whether a provider may receive client material, what retention terms apply, what a client's engagement terms say. Work out what would have to be asked and of whom, note what would turn on the answer, and move on — see security-review. A boundary, not a blocker.

Work the map, one question per session

Answer one question at a time. Several look-it-ups can run together, since they do not depend on each other.

When a question is answered: record one line in Decisions so far pointing at wherever the detail actually lives — the experiment README, the decision record, the evaluation — and delete it from the open list. The map is an index, not a store; a decision written in two places will eventually disagree with itself.

Then look at the fog again. An answer usually makes something specifiable that was not before; promote it, and clear that patch from Not yet specified so it exists in one place only. If the answer reveals that a question sits beyond the destination, move it to Out of scope rather than resolving it — ruling something out is a scoping act, not a step on the route.

Charting produces decisions, not deliverables

Do not start building during this phase. The map exists to make the first experiment choosable, and the pull to skip ahead and write code is the useful signal: when you find yourself wanting to build rather than decide, the map has done its job. Stop charting, go to section 5, and design the experiment.

That is the completion criterion. There is no requirement to empty the map first — most maps still have open questions when the first experiment starts, and some of them are only answerable by running it.

5. Choose the lightest maturity level

Use:

  • experiments/ for a meaningful hypothesis or prototype — including the very first version. A feature starts here on its first line rather than growing into it from a scratch file, because the question, the fixtures and the write-up are most of what an experiment is, and none of them survives a file that was never meant to be kept;
  • tmp/ only for a one-off utility beside the work — rename these files, check whether this export parses. tmp/ is for things you do; experiments/ is for things you find out. If the answer is something you would want recorded, it was never a tmp/ job;
  • src/legal_lab/ only once a capability is stable enough to reuse or maintain;
  • a product surface only once somebody other than the owner needs to use the result — and the first one is a script that writes a page they can open, not an application (AGENTS.md, Where things go; docs/WORKING_PROCESS.md phase G carries what that first surface actually is).

Use synthetic or public data by default.

6. Define the first milestone

Create or update the appropriate project/experiment brief from the repository templates.

Make clear:

  • what we are trying to learn;
  • what the first version will do;
  • what it deliberately will not do;
  • how we will know whether it worked;
  • the main failure modes worth watching;
  • who would have to accept the output, and what would make them accept it.

In proportion to how far the project has come, work through what acceptance would take:

  • Is the workflow actually better? Compare against what the person does today, including the steps they would still perform. A tool that automates six minutes of a ten-minute task and adds four minutes of verification has saved nothing.
  • Is review cheaper than the original work? The question that decides adoption.
  • Is it clear what the software did and what the model did? A user who cannot tell cannot calibrate how carefully to read.
  • How is uncertainty presented? "No deadline found" and "this document may contain a deadline I could not resolve" are different statements, and only one prompts a person to look.
  • Is correcting the output easy, and does the correction stick? A tool that must be fought is not trusted, however accurate it is.
  • Does it fit how the work is actually done? Making someone leave the system they live in all day carries a cost that is usually underestimated.
  • Who carries the residual risk, and do they know it? A lawyer remains responsible for what they sign. Software that obscures which parts were machine-produced makes that responsibility harder to discharge.

That last point is easy to defer and expensive to defer. A capability is adopted when checking its output is cheaper than doing the work by hand, and abandoned when it is not — regardless of how accurate it is. Ask early what the person would need to see next to each result in order to trust it in seconds rather than re-reading the source. Often the answer is the supporting sentence, and knowing that changes what the first version should return.

This is not a reason to build an interface. Terminal output is the right surface for almost every first experiment. It is a reason to know what acceptance would require.

One thing follows from it that is easy to defer indefinitely: the owner cannot answer the acceptance question themselves. Whether reviewing an output is cheaper than doing the work is a judgement belonging to whoever would use it, and the person who built the tool is the worst-placed person in the room to make it. At some point one real output needs to go in front of one colleague. That is not a reason to build a product — a file they can open is enough — but it is worth naming as the thing the experiment is eventually for, because a further round of accuracy is always the more comfortable alternative.

6a. What the first hour of building actually looks like

Everything above is framing, and framing is the part the owner can do from their own expertise. This is the part they cannot, and "then begin the smallest useful implementation" is where a first project stalls if nothing follows it. Say what happens next, concretely.

One file, inside the experiment. Not a directory, not a module, not a place to put things later — but in experiments/<nnn>-<name>/ from the first line rather than in a scratch file that gets moved once it looks respectable. If the owner asks where something should go, the answer now is "in this file" — and say why, because restraint that goes unexplained reads as an omission rather than a decision.

The question at the top, in English, before any code. The experiment's README carries it properly; one line at the top of the script says which part of it this file answers. A file that states what it is for stops growing into a small unplanned product.

The smallest thing that could produce an answer, then run it before it works. Not after. The first error is the point: reading one together, once, teaches more about how software actually behaves than a working script does — and AGENTS.md asks you to do that once per kind of error, so this is the occasion it is spent on. The owner should be the one to run the command.

Print the intermediate value, not just the answer. A script that prints only its result is opaque when the result is wrong. One line showing what was found before it was interpreted is how the owner learns to see inside a program, and it costs nothing to remove later.

Then trace it once. One real input, naming the file and line at each step, so the answer to "what does this do?" is theirs. Once per piece of work, not per change — docs/READING_CODE.md is the habit written down, and worth handing over the first time the owner is reading rather than running.

And hand them one safe change to make themselves. Tracing is reading; this is the move that removes the fear, and it is a different one. Name the single line that would move the result most, say what you expect to happen, and let them edit it and run it. The gap between "the agent wrote this and I followed it" and "I changed it and watched the number move" is where the apprehension about code actually lives, and no amount of tracing crosses it. Once per experiment, on the line that decides something, with the safety said out loud: Git is holding the original and git checkout <file> puts it back. docs/READING_CODE.md has this worked end to end on experiment 001, including what the numbers do.

What not to do: do not open with a structure, do not add a dependency, do not write tests for code whose shape will change within the hour, and do not apologise for how small it is. The size is the method.

Then begin the smallest useful implementation.

7. Teach as decisions arise

Do not front-load a software-engineering course.

When the project creates a reason to introduce a concept, explain:

  1. the practical problem;
  2. the change being proposed;
  3. why it helps here;
  4. the technical name, if useful;
  5. when it would be unnecessary;
  6. why it matters in legal technology;
  7. how the owner could explain the decision externally, when useful.

When not to use this skill

  • The idea has already been framed and the work is now implementation. Re-running discovery on a project that already has a brief wastes the owner's time and makes the repository feel bureaucratic.
  • The request is a small addition inside an existing experiment.
  • The owner is asking a direct technical question and wants an answer, not a workshop.

Use it when the direction is genuinely unsettled, not whenever new code is written.

Section 4 has a narrower trigger still. Charting a map is slower and denser than the rest of this skill, and imposing it on a well-scoped idea turns a twenty-minute conversation into paperwork. Reach for it only when there is genuinely more than one thing to find out and the answers depend on each other.

Handoff to other skills

This skill begins the project. It does not need to remain as a ceremony for every coding task.

Hand off to at most one of the following, and note the rest rather than running them. Following every applicable handoff in sequence turns one request into five reviews, which is the bureaucracy this repository exists to avoid, arrived at one reasonable step at a time.

Automatically move into or combine with:

  • architecture-review when the experiment is growing, code is being promoted/reused, a new module/service/database/API/framework is proposed, or the owner asks how to structure something;
  • security-review when real/confidential data, users, credentials, external providers, databases, permissions, AI tools, or consequential actions are introduced — and to work through any Not ours to settle entry on the map;
  • evaluation-review as soon as an AI behaviour is being called good, before it is relied on or promoted;
  • learning-review after a meaningful milestone or architectural decision so the owner consolidates what the project has taught;
  • interview-review once the project contains a genuine decision, result, failure, evaluation, or safeguard worth discussing externally.

After any review, return to normal building and iteration unless the review identifies a blocker.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.