typedai: Instructions file for Codex

General code standards

Do not update project level configuration files unless explicitly instructed to.

Use async/await where possible

Test exceptional cases first and return/throw early.

Never edit files name CONVENTIONS.md, .cursorrules, DOCS.md unless explicitly instructed to.

Prefer composing small descriptive functions over large complex functions.

Clean Code style guidelines

Example

Original code

async function cloneProject(projectPathWithOrg: string, branchOrCommit: string): Promise<string> {
    const paths = projectPathWithOrg.split('/');
    if(paths.length !== 2) {
        throw new Error(`${projectPathWithOrg} must be in the format organisation/project`);
    }
    const org = paths[0];
    const project = paths[1];
    
    const agent = agentContext();
    // Determine base path: system-wide or agent-specific
    const basePath = agent?.useSharedRepos ? join(systemDir(), 'github') : agent ? join(agentDir(), 'github') : join(systemDir(), 'github'); // Default to systemDir if no agent context
    
    // Construct the full target path for the project
    const targetPath = join(basePath, org, project);
    
    // Ensure the base directory and organization directory exist
    await fs.mkdir(basePath, {recursive: true});
    await fs.mkdir(join(basePath, org), {recursive: true});
    
    // remainder of the clone function ...
}

Analysis

paths.length validation can be on one line. The assignment to basePath is too complex with multiple ternary statements. 'github' is repeated many times. The variable which changes in the ternary expression should be extract out. Group together the statements which setup the folder. Add a comment at the start of the block of statements for readability. Change targetPath to repoPath, which has more relevant meaning. "Ensure the base directory and organization directory exist" comment doesn't add value. We can assume the reader knows fundamental built in APIs like fs.mkdir Having two fs.mkdir() calls is unnecessary